Подключение 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 должно отправляться в тот момент, когда пользователь попадает под условие показа предложения или выпадает из этого условия (например, начинает/заканчивает действовать акция в приложении).

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

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

** — обязательный параметр для рекомендации 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 должно отправляться непосредственно после покупки/попытки покупки предложения, участвующего в рекомендации.

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

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

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

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 должно отправляться при каждом открытии/закрытии карточки/экрана с предложением, участвующим в рекомендации.

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

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

** — обязательный параметр для рекомендации 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.

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

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

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

Параметры:

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

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

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

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

Параметры:

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

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

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

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: рекомендуемое количество товара в предложении

Коды ответов

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