Войти

Подключение Personalize Премиум план

Чтобы подключить MyTracker Personalize к мобильному приложению, настройте передачу событий через MyTracker SDK и подключите Personalize API.

Интеграция MyTracker SDK

MyTracker SDK соберёт статистику по пользователям вашего приложения и сформирует базу данных необходимую для построения рекомендаций.

  1. Подключите SDK к приложениям, с которыми будет взаимодействовать пользователь. Подробнее см. разделы iOS, Android, Unity.
  2. Убедитесь, что вы настроили трекинг и верификацию платежей. Подробнее см. раздел Трекинг покупок.
  3. Выберите способ идентификации пользователей:
    • Если ваше приложение предусматривает регистрацию, и каждый пользователь получает уникальный идентификатор, то настройте трекинг пользователей через параметр customUserId (см. документацию на iOS, Android, Unity).
    • customUserId не должен меняться с момента первого запуска приложения

    • Если в приложении нет системы регистрации или уникальный идентификатор присваивается не с самого начала использования приложения, то настройте получение instanceId (см. документацию на iOS, Android, Unity) и отправляйте instanceId в параметре customUserId.
    • instanceId идентифицирует физическое устройство, но не пользователя, поэтому рекомендация для одного и того же пользователя может отличаться на разных платформах


  4. Согласно инструкции по передаче произвольных событий (для iOS, Android, Unity), настройте отправку следующих событий:
    • Триггер предложения offer_trigger
    • Покупка предложения purchase_offer
    • Открытие/закрытие карточки предложения offer_card
    • Состояние аккаунта пользователя account_status

    Все события должны отправляться с устройства (не с сервера). При отправке событий, рекомендуем указывать параметр flush, чтобы события не скапливались в буфере, (см. инструкцию по принудительной отправке событий для iOS, Android, Unity).

    Все параметры событий должны быть переданы в строковом виде, в качестве разделителя для вещественных чисел используйте точку.

    Ниже дано подробное описание перечисленных событий и их параметров.

Параметры placement_id, sku, и payload должны быть указаны при создании рекомендации в MyTracker. Подробнее

Триггер предложения

Событие offer_trigger должно отправляться в тот момент, когда пользователь попадает под условие показа предложения или выпадает из этого условия (например, начинает/заканчивает действовать акция в приложении).

Параметры события должны быть переданы в виде строки:

Название параметра Описание Пример
action* Если пользователь начал попадать под условия показа предложения, то значение параметра — "start". Если перестал попадать — "end". "start"
placement_id* ID места размещения предложения "A"
sku** Название бандла в магазине приложений (не уникально и может быть использовано сразу для нескольких предложений в магазине) "com.app.10dollars"
payload** Уникальное название предложения внутри приложения "offer.for.unpaid"
timestamp* Дата и время события в timestamp (UTC+3 в секундах) "1597316958"

* — обязательный параметр.

** — обязательный параметр для рекомендации item и необязательный для set.

Пример кода:

let eventCustomParams = [
    "action": "start",
    "placement_id": "A",
    "payload": "offer.for.unpaid",
    "timestamp": "1597316958"
]
MRMyTracker.trackEvent(withName: "offer_trigger", eventParams:eventCustomParams)
val eventCustomParams = HashMap<String, String>()
    eventCustomParams["action"] = "start";
    eventCustomParams["placement_id"] = "A";
    eventCustomParams["payload"] = "offer.for.unpaid";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.trackCustomEvent("offer_trigger", eventCustomParams);
var IDictionary<String, String> eventCustomParams = new Dictionary<String, String>();
    eventCustomParams["action"] = "start";
    eventCustomParams["placement_id"] = "A";
    eventCustomParams["payload"] = "offer.for.unpaid";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.TrackEvent("offer_trigger", eventCustomParams));

Покупка предложения

Событие purchase_offer должно отправляться непосредственно после покупки/попытки покупки предложения, участвующего в рекомендации.

Если в покупке несколько предложений, то каждый из них должен быть отправлен отдельным событием.

Параметры события должны быть переданы в виде строки:

Название параметра Описание Пример
placement_id* ID места размещения предложения "A"
placement_type Тип места размещения предложения (поскольку карточка с предложением может быть доступна с разных экранов приложения).

Значение по умолчанию: "any"
"main"
"store"
"pop-up"
sku* Название бандла в магазине приложений (не уникально и может быть использовано сразу для нескольких предложений в магазине) "com.app.10dollars"
payload* Уникальное название предложения внутри приложения "offer.for.unpaid"
result* Успех покупки (списание денег) "true"
"false"
offer_id* Идентификатор предложения "42"
timestamp* Дата и время покупки в timestamp (UTC+3 в секундах) "1597316958"

* — обязательный параметр.

let eventCustomParams = [
    "placement_id":"A",
    "placement_type":"store",
    "sku": "com.app.10dollars",
    "payload": "offer.for.unpaid",
    "result": "true",
    "offer_id": "42",
    "timestamp":"1597316958"
]
MRMyTracker.trackEvent(withName: "purchase_offer", eventParams:eventCustomParams)
val eventCustomParams = HashMap<String, String>()
    eventCustomParams["placement_id"] = "A";
    eventCustomParams["placement_type"] = "store";
    eventCustomParams["sku"] = "com.app.10dollars";
    eventCustomParams["payload"] = "offer.for.unpaid";
    eventCustomParams["result"] = "true";
    eventCustomParams["offer_id"] = "42";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.trackCustomEvent("purchase_offer", eventCustomParams);
var IDictionary<String, String> eventCustomParams = new Dictionary<String, String>();
    eventCustomParams["placement_id"] = "A";
    eventCustomParams["placement_type"] = "store";
    eventCustomParams["sku"] = "com.app.10dollars";
    eventCustomParams["payload"] = "offer.for.unpaid";
    eventCustomParams["result"] = "true";
    eventCustomParams["offer_id"] = "42";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.TrackEvent("purchase_offer", eventCustomParams));

Открытие/закрытие карточки предложения

Событие offer_card должно отправляться при каждом открытии/закрытии карточки/экрана с предложением, участвующим в рекомендации.

Параметры события должны быть переданы в виде строки:

Название параметра Описание Пример
action* Действие с карточкой предложения: открытие "open" или закрытие "close". Если пользователь открыл и закрыл карточку, то нужно отправить 2 события с разным action "open"
placement_id* ID места размещения предложения "A"
placement_type Тип места размещения предложения (поскольку карточка с предложением может быть доступна с разных экранов приложения).

Значение по умолчанию "any"
"main"
"store"
"pop-up"
sku** Название бандла в магазине приложений (не уникально и может быть использовано сразу для нескольких предложений в магазине) "com.app.10dollars"
payload** Уникальное название предложения внутри приложения "offer.for.unpaid"
offer_id* Идентификатор предложения "42"
timestamp* Дата и время открытия/закрытия карточки в timestamp (UTC+3 в секундах) "1597316958"

* — обязательный параметр.

** — обязательный параметр для рекомендации item и необязательный для set.

let eventCustomParams = [
    "action": "open",
    "placement_id": "A",
    "placement_type": "store",
    "sku": "com.app.10dollars",
    "payload": "offer.for.unpaid",
    "offer_id": "42",
    "timestamp":"1597316958"
]
MRMyTracker.trackEvent(withName: "offer_card", eventParams:eventCustomParams)
val eventCustomParams = HashMap<String, String>()
    eventCustomParams["action"] = "open";
    eventCustomParams["placement_id"] = "A";
    eventCustomParams["placement_type"] = "store";
    eventCustomParams["sku"] = "com.app.10dollars";
    eventCustomParams["payload"] = "offer.for.unpaid";
    eventCustomParams["offer_id"] = "42";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.trackCustomEvent("offer_card", eventCustomParams);
var IDictionary<String, String> eventCustomParams = new Dictionary<String, String>();
    eventCustomParams["action"] = "open";
    eventCustomParams["placement_id"] = "A";
    eventCustomParams["placement_type"] = "store";
    eventCustomParams["sku"] = "com.app.10dollars";
    eventCustomParams["payload"] = "offer.for.unpaid";
    eventCustomParams["offer_id"] = "42";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.TrackEvent("offer_card", eventCustomParams));

Состояние аккаунта пользователя

Событие account_status должно отправляться не реже, чем при каждом запуске приложения.

В таблице ниже приведены общие параметры, которые могут охарактеризовать состояние аккаунта. Попробуйте найти аналог в своём приложении для максимального числа перечисленных параметров. Чтобы добавить дополнительные параметры, свяжитесь со службой поддержки MyTracker.

Параметры события должны быть переданы в виде строки:

Название параметра Описание Пример
in_game_currency_<name> Любые балансы внутриигровых ресурсов, где name — название ресурса "444"
in_game_currency_diamonds Любые балансы внутриигровых ресурсов, например кристаллы "5"
in_game_currency_food Любые балансы внутриигровых ресурсов, например еда "5"
in_game_currency_gold Любые балансы внутриигровых ресурсов, например золото "5"
account_level Уровень аккаунта "5"
clan ID клана "123123123",
"0" — если не состоит в клане
achievements_count Количество достижений "12"
ranking Рейтинг аккаунта "99"
power Ценность аккаунта "12312312"
friends_count Количество друзей "56"
matches_count Количество матчей "21312"
wins_count Количество побед "12121"
timestamp* Дата и время события в timestamp (UTC+3 в секундах) "1597316958"

* — обязательный параметр.

let eventCustomParams = [
    "in_game_currency_diamonds": "5",
    "in_game_currency_food": "10001",
    "in_game_currency_gold": "356",
    "account_level": "5",
    "clan": "123123123",
    "achievements_count": "12",
    "ranking": "99",
    "power": "12312312",
    "friends_count": "56",
    "matches_count": "21312",
    "wins_count": "12121",
    "timestamp": "1597316958"
]
MRMyTracker.trackEvent(withName: "account_status", eventParams:eventCustomParams)
val eventCustomParams = HashMap<String, String>()
    eventCustomParams["in_game_currency_diamonds"] = "5";
    eventCustomParams["in_game_currency_food"] = "10001";
    eventCustomParams["in_game_currency_gold"] = "356";
    eventCustomParams["account_level"] = "5";
    eventCustomParams["clan"] = "123123123";
    eventCustomParams["achievements_count"] = "12";
    eventCustomParams["power"] = "12312312";
    eventCustomParams["friends_count"] = "56";
    eventCustomParams["matches_count"] = "21312";
    eventCustomParams["wins_count"] = "12121";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.trackCustomEvent("account_status", eventCustomParams);
var IDictionary<String, String> eventCustomParams = new Dictionary<String, String>();
    eventCustomParams["in_game_currency_diamonds"] = "5";
    eventCustomParams["in_game_currency_food"] = "10001";
    eventCustomParams["in_game_currency_gold"] = "356";
    eventCustomParams["account_level"] = "5";
    eventCustomParams["clan"] = "123123123";
    eventCustomParams["achievements_count"] = "12";
    eventCustomParams["power"] = "12312312";
    eventCustomParams["friends_count"] = "56";
    eventCustomParams["matches_count"] = "21312";
    eventCustomParams["wins_count"] = "12121";
    eventCustomParams["timestamp"] = "1597316958";
MyTracker.TrackEvent("account_status", eventCustomParams));

Интеграция с Personalize API

Через запросы к Personalize API вы можете получать рекомендации в режиме реального времени и показывать персональные предложения внутри приложения.

Отправка запроса

Ознакомьтесь с особенностями отправки запросов:

  • Запросы с разных платформ (iOS, Android, Unity) должны приходить отдельно, каждый со своим sdk_key. Чтобы получить sdk_key нужно подключить SDK к приложению.
  • Выберите один из вариантов отправки запросов:
    • С мобильного устройства. В этом случае оптимальным будет асинхронный запрос на получение рекомендаций сразу после загрузки приложения.
    • С бэкенда мобильного приложения. Рекомендуем отправлять запросы не раньше, чем пользователь получит доступ к рекомендуемым товарам, чтобы MyTracker успел собрать как можно больше сведений о пользователе. Повторные запросы необходимо совершать как минимум раз в сутки.
  • Предусмотрите следующие возможности:
    • Кеширование последних рекомендаций на стороне клиента. Это нужно для того, чтобы при неполадках в сети, задержке в получении рекомендации или ошибке со стороны сервера, отдать самую актуальную рекомендацию для пользователя.
    • Асинхронная отправка запроса.
    • Использование параметра reset в запросах к API (опционально). Если reset=True, то сервис отдает самую свежую рекомендацию для пользователя (цена товара может измениться). Если reset=False, то будет возвращена последняя выданная ранее рекомендация (цена товара останется прежней).

Синтаксис запроса

Чтобы обратиться к Personalize API, необходимо выполнить запрос следующего вида:

https://mlapi.tracker.my.com/v1/recommendation/имя_метода
  • v1 — версия Personalize API;
  • имя метода — имя вызываемого метода: item, set.

Отправить запрос можно с помощью Swagger UI

Запрос на рекомендацию item

Используйте метод item для получения рекомендации на один предмет.

Endpoint: https://mlapi.tracker.my.com/v1/recommendation/item

Параметры:

Название параметра Описание Тип Пример
sdk_key* Ключ приложения, встраиваемый в MyTracker SDK, выдается после добавления приложения Строка 00001234567890123456
custom_user_id* Идентификатор пользователя, переданный через MyTracker SDK. Определяет отдельно взятого пользователя. Строка 1234
flat Флаг изменяет формат ответа. Доступные значения:
0 — поле data является словарём
1 — поле data является массивом

Значение по умолчанию: 0
Число 0
reset Признак сброса рекомендаций при последующих запросах. Доступные значения:
0 — не сбрасывать
1 — сбрасывать

Значение по умолчанию: 1
Число 1
placement_ids Идентификаторы мест размещения предложения. Если параметр не указан, то рекомендация будет сформирована по всем местам размещения предложения Массив строк A, B, C

* — обязательный параметр.

Примеры запросов

Пример запроса:

curl --location --request GET 'https://mlapi.tracker.my.com/api/v1/recommendation/item?sdk_key=00001234567890123456&custom_user_id=1234&placement_ids=A&placement_ids=B&placement_ids=C'

Формат ответа:

{
  "data": {
    "A":{
      "test_id": 0,
      "group_id": 0,
      "placement_id": "string",
      "offer": {
        "offer_id": "string",
        "subitems": [
          {
            "sku": "string",
            "payload": "string",
            "price": 0,
            "value": 0,
            "discount_price": 0,
            "discount_value": 0
          }
        ]
      },
    },
    "B":{}
    "C":{}
  }
}

Ответ включает следующие данные:

  • test_id: идентификатор A/B теста
  • group_id: идентификатор группы, к которой относится пользователь группа для рекомендаций или контрольная группа
  • placement_id: идентификатор места размещения предложения
  • offer_id: идентификатор предложения
  • price: цена предложения по умолчанию (можно не использовать)
  • value: количество товара в предложении по умолчанию (можно не использовать)
  • discount_price: рекомендуемая цена предложения
  • discount_value: рекомендуемое количество товара в предложении

Пример запроса с flat=1:

curl --location --request GET 'https://mlapi.tracker.my.com/api/v1/recommendation/item?sdk_key=00001234567890123456&custom_user_id=1234&placement_ids=A&placement_ids=B&placement_ids=C&flat=1'

Формат ответа с flat=1:

{
  "data": [
    {
      "test_id": 0,
      "group_id": 0,
      "placement_id": "string",
      "offer": {
        "offer_id": "string",
        "subitems": [
          {
            "sku": "string",
            "payload": "string",
            "price": 0,
            "value": 0,
            "discount_price": 0,
            "discount_value": 0
          }
        ]
      },
    },
    {}
    {}
  ]
}

Ответ включает следующие данные:

  • test_id: идентификатор A/B теста
  • group_id: идентификатор группы, к которой относится пользователь: группа для рекомендаций или контрольная группа
  • placement_id: идентификатор места размещения предложения
  • offer_id: идентификатор предложения
  • sku: название бандла в магазине приложений (не уникально и может быть использовано сразу для нескольких предложений в магазине)
  • payload: уникальное название предложения внутри приложения
  • price: цена предложения по умолчанию (можно не использовать)
  • value: количество товара в предложении по умолчанию (можно не использовать)
  • discount_price: рекомендуемая цена предложения
  • discount_value: рекомендуемое количество товара в предложении

Запрос на рекомендацию set

Используйте метод set для получения рекомендаций на набор предметов.

Endpoint: https://mlapi.tracker.my.com/v1/recommendation/set

Параметры:

Название параметра Описание Тип Пример
sdk_key* Ключ приложения, встраиваемый в MyTracker SDK, выдается после добавления приложения Строка 00001234567890123456
custom_user_id* Идентификатор пользователя, переданный через MyTracker SDK. Определяет отдельно взятого пользователя. Строка 1234
flat Флаг изменяет формат ответа. Доступные значения:
0 — поле data является словарём
1 — поле data является массивом

Значение по умолчанию: 0
Число 0
reset Признак сброса рекомендаций при последующих запросах. Доступные значения:
0 — не сбрасывать
1 — сбрасывать

Значение по умолчанию: 1
Число 1
placement_ids Идентификаторы мест размещения предложения. Если параметр не указан, то рекомендация будет сформирована по всем местам размещения предложения Массив строк A, B, C

* — обязательный параметр.

Примеры запросов

Пример запроса:

curl --location --request GET 'https://mlapi.tracker.my.com/api/v1/recommendation/set?sdk_key=00001234567890123456&custom_user_id=1234&placement_ids=A&placement_ids=B&placement_ids=C'

Формат ответа:

{
  "data": {
    "A":{
      "test_id": 0,
      "group_id": 0,
      "placement_id": "string",
      "offer": {
        "offer_id": "string",
        "subitems": [
          {
            "sku": "string",
            "payload": "string",
            "price": 0,
            "value": 0,
            "discount_price": 0,
            "discount_value": 0
          }
        ]
      },
    },
    "B":{}
    "C":{}
  }
}

Пример запроса с flat=1:

curl --location --request GET 'https://mlapi.tracker.my.com/api/v1/recommendation/set?sdk_key=00001234567890123456&custom_user_id=1234&placement_ids=A&placement_ids=B&placement_ids=C&flat=1'

Формат ответа с flat=1:

{
  "data": [
    {
      "test_id": 0,
      "group_id": 0,
      "placement_id": "string",
      "offer": {
        "offer_id": "string",
        "subitems": [
          {
            "sku": "string",
            "payload": "string",
            "price": 0,
            "value": 0,
            "discount_price": 0,
            "discount_value": 0
          }
        ]
      },
    },
    {}
    {}
  ]
}

Оба ответа включают в себя следующие данные:

  • test_id: идентификатор A/B теста
  • group_id: идентификатор группы, к которой относится пользователь: группа для рекомендаций или контрольная группа
  • placement_id: идентификатор места размещения предложения
  • offer_id: идентификатор предложения
  • sku: название бандла в магазине предложений (не уникально и может быть использовано сразу для нескольких предложений в магазине)
  • payload: уникальное название предложения внутри приложения
  • price: цена предложения по умолчанию (можно не использовать)
  • value: количество товара в предложении по умолчанию (можно не использовать)
  • discount_price: рекомендуемая цена предложения
  • discount_value: рекомендуемое количество товара в предложении

Коды ответов

Код Описание
200 Запрос был успешно обработан
400 Ошибка запроса, параметры не прошли валидацию

Перед запуском рекомендации, проверьте передачу событий и показ предложений на тестовых пользователях. См. раздел Тестирование и запуск рекомендации.

Была ли эта статья полезна?