Начало работы с модулем MRGSAnalytics🔗

Для интеграции модуля MRGSAnalytics необходимо выполнить несколько простых шагов. При подключении данного модуля, MRGS будет автоматически обогащать все свои события параметром appsflyerId, таким образом, можно будет связать данные в MRGS с данными из AppsFlyer.

Шаг 1. Импортируйте модуль MRGSAnalytics🔗

• Добавьте модуль MRGSAnalytics

  Unity:

  Добавление в проект (общая инструкция)

  Unity Package ManagerРучная интеграция (unitypackage или tgz)

  Шаг 1. Добавьте источники

  Для того, чтобы добавить MRGS в проект через Unity Package Manager (доступно с Unity 2018+) просто добавьте в файл Packages/manifest.json раздел scopedRegistries, добавив в него следующую запись:

  {
      "dependencies": {
          ...
      },
      "scopedRegistries": [
              {
                  "name": "MRGS",
                  "url": "https://mrgs-nexus.my.games/repository/mrgs-uninty-plugins/",
                  "scopes": [
                      "games.my.mrgs"
                  ]
              }
      ]
  }
  

  Альтернативно, можно нажать Edit -> Project Settings -> Package Manager -> '+' in scoped registry section, и заполнить поля в соответствии с данными выше.

  Шаг 2. Добавьте зависимость

  • Нажмите Window -> Package Manager -> select 'Packages: MyRegistries' from dropdown list, выберите пакет MRGSAnalytics из списка, затем нажмите "Install"
  • Импортируйте модуль: using MRGS;

  • Загрузите последнюю версию библиотеки. Распакуйте архив.
  • (Для интеграции unitypackage) В Unity нажмите Assets -> Import Package -> Custom Package, и выберите пакет games.my.mrgs.analytics.unitypackage из скачанного архива.
  • (Для интеграции tgz) В Unity нажмите Window -> Package Manager -> '+' -> Add package from tarball, и выберите пакет games.my.mrgs.analytics-<version>.tgz из скачанного архива.
  • Импортируйте модуль: using MRGS;

  iOS:

  Добавление в проект (общая инструкция)

  Swift Package ManagerCocoapodsCarthageРучная интеграция

  Шаг 1. Добавьте зависимости

  Через Package collection

  • В Xcode выберите File > Add Packages
  • Выберите «+» > "Add Swift Package Collection"
  • Вставьте URL: https://mrgs-nexus.my.games/repository/ios-sdks/MRGSPackageCollection.json
  • Выберите модуль MRGSAnalytics из "MRGS Package Collection".
  • Или вы можете выбрать пакет «MRGS» из "MRGS Package Collection" (содержит все модули mrgs в качестве продуктов), а затем выбрать только продукт "MRGS/Analytics".

  Отдельными пакетами

  • В Xcode выберите File > Add Packages
  • В строке поиска в правом верхнем углу вставьте URL: https://mrgs-gitea.my.games/mrgs/mrgsanalytics-ios-sdk.git
  • Добавьте модуль в свой проект
  • Или вы можете вставить URL https://mrgs-gitea.my.games/mrgs/ios-sdks.git, чтобы подключить пакет "MRGS", который содержит все модули mrgs в качестве продуктов, а затем выбрать только продукт "MRGS/Analytics".

  Шаг 2. Добавьте поддержку категорий ObjectiveC

  • В настройках проекта установите флаг -ObjC в поле "Other linker Flags".
  • Импортируйте модуль в коде: @import MRGServiceKit; или @import MRGSAnalytics; или #import <MRGSAnalytics/MRGSAnalytics.h>

  Шаг 1. Добавьте источники

  В вашем podfile добавьте источники в начало файла:

  source 'https://github.com/CocoaPods/Specs.git' # For main repo
  source 'https://mrgs-gitea.my.games/mrgs/cocoapods-specs.git'  # For MRGS repo
  

  Шаг 2. Добавьте зависимости

  В target добавьте последнюю версию MRGSAnalytics:

  Чтобы добавить через subspecs:

  target 'MyProject' do
      pod 'MRGS', '~> 5.0.0', :subspecs => ['Analytics']
  end
  

  Для добавления через отдельные модули:

  target 'MyProject' do
      pod 'MRGSAnalytics', '~> 5.0.0'
  end
  

  Чтобы добавить все модули mrgs:

  target 'MyProject' do
      pod 'MRGS/AllKits', '~> 5.0.0'
  end
  

  Шаг 3. Установите зависимости

  • Выполните pod install (или pod install --repo-update если необходимо)
  • Импортируйте модуль в коде: @import MRGServiceKit; или @import MRGSAnalytics; или #import <MRGSAnalytics/MRGSAnalytics.h>

  Шаг 1. Добавьте зависимости

  Добавьте зависимость в ваш Cartfile:

  binary "https://mrgs-nexus.my.games/repository/ios-sdks/MRGSAnalytics/MRGSAnalytics.json" ~> 5.0.0
  

  Шаг 2. Установите зависимости

  • Выполните carthage update --use-xcframeworks
  • Добавьте загруженные фреймворки в свой проект (убедитесь, что опция "do not embed" включена)
  • В настройках проекта установите флаг -ObjC в поле "Other linker Flags".
  • Импортируйте модуль в коде: @import MRGServiceKit; или @import MRGSAnalytics; или #import <MRGSAnalytics/MRGSAnalytics.h>

  • Загрузите последнюю версию библиотеки. Распакуйте архив.

  • Добавьте MRGSAnalytics.xcframework из скачанного архива в ваш проект (Перетащите библиотеки в раздел "Linked frameworks and Libraries") (для совместимости в архиве также находится MRGSAnalytics.framework - fat framework старого вида)

  • В настройках проекта установите флаг -ObjC в поле "Other linker Flags".

  • Импортируйте модуль в коде: @import MRGSAnalytics; или #import <MRGSAnalytics/MRGSAnalytics.h>
  • Также, вы можете добавить из архива файлы MRGServiceKit.h и module.modulemap в свой проект, либо в настройках проекта укажите путь до них в разделе Build Settings -> Header search paths. Теперь вместо импорта каждого из наших фреймворков по отдельности, вы можете импортировать только один заголовочный файл: @import MRGServiceKit;

  Android:

  Gradle установкаРучная установка

  Добавьте зависимость в build.gradle файл:

  dependencies {
      def mrgsVersion = "6.x.x"
  
      implementation "games.my.mrgs:analytics:$mrgsVersion"
  }
  

  Скопируйте файл MRGSAnalytics.aar в директорию libs вашего проекта. Добавьте необходимые зависимости в build.gradle файл

  dependencies {
      //...
      implementation(name: 'MRGSAnalytics', ext:'aar')
  
      implementation 'androidx.appcompat:appcompat:1.6.1'
      implementation 'com.appsflyer:af-android-sdk:6.12.1'
      implementation 'com.appsflyer:adrevenue:6.9.1'
      implementation "com.android.installreferrer:installreferrer:2.2"
  }
  

dependencies {
    //... other dependencies
    implementation 'com.appsflyer:oaid:6.1.1'
    implementation files('libs/oaid_sdk_1.0.23.aar')
}

Шаг 2. Предварительная настройка🔗

При инициализации MRGS необходимо включить AppsFlyer в параметрах внешних SDK, а также указать ключ разработчика (devKey) и Apple AppID (appId). Для Android вместо appId можно передать пустую строку

using MRGS;

public class MasterController : MonoBehaviour
{
    void Awake()
    {
        //Настройка параметров MRGS
        // ...

        var sdkParams = new MRGSExternalSDKParams
        {
            // ...
            // For Android, you can specify an empty string instead of APPLE_APP_ID
            AppsFlyerParams = new MRGSAppsFlyerParams(APPS_FLYER_DEVKEY, APPLE_APP_ID)
            {
                Debug = false
            }
            // ...
        };

        // Configuring External SDKs and initializing MRGS
        // ...

        MRGService.Instance.Initialize(serviceParams, sdkParams);
    }
}

@import MRGService;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //Настройка параметров MRGS
    // ...
    //Настройка Внешних SDK

    MRGSAppsFlyerParams *appsFlyerParams = [[MRGSAppsFlyerParams alloc] initWithDevKey:<APPS_FLYER_DEVKEY> appleAppId:<APPLE_APP_ID>];

    NSArray *externalParams = @[ ..., appsFlyerParams];
    [MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];
}

import games.my.mrgs.MRGSExternalSDKParams;
import games.my.mrgs.MRGSExternalSDKParams.AppsFlyerParams;
import games.my.mrgs.MRGService;
import games.my.mrgs.MRGServiceParams;

public class YourApplicationClass extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Setting MRGService
        final MRGServiceParams serviceParams = ...;
        // Setting External SDKs
        final AppsFlyerParams appsFlyerParams = AppsFlyerParams.init("<APPS_FLYER_DEVKEY>");
        appsFlyerParams.setDebuggable(false);

        final MRGSExternalSDKParams externalSDKParams = MRGSExternalSDKParams.newInstance();
        externalSDKParams.appsFlyerParams = appsFlyerParams;

        MRGService.service(context, serviceParams, externalSDKParams);
    }
}

Настройка работы с CustomerUserId в AppsFlyer🔗

По умолчанию, MRGS выставит в поле CustomerUserId значение UserId, переданное нам через метод SetUserId().

Задержка старта до выставления UserId🔗

В случае, если вам необходимо отложить старт AppsFlyer до выставления UserId (чтобы событие установки ушло уже с идентификатором пользователя), вам необходимо выставить дополнительный флаг:

appsFlyerParams.WaitForCustomerUserId = true;

appsFlyerParams.waitForCustomerUserId = true;

appsFlyerParams.setWaitForCustomerUserIdEnabled(true);

Установка идентификатора устройства (deviceId) в CustomerUserId🔗

В старых версиях MRGS по умолчанию в поле CustomerUserId выставлялось значение MRGS Device Id. Чтобы вернуть старое поведение (до версии 6.0.0-b), достаточно при настройке параметров при старте MRGS выставить флаг:

appsFlyerParams.UseDeviceIdAsUserId = true;

appsFlyerParams.useDeviceIdAsUserId = true;

appsFlyerParams.setUseDeviceIdAsUserId(true);

Установка собственного CustomerUserId🔗

Если вы хотите установить собственный customerUserID в AppsFlyer, воспользуйтесь методом:

MRGSAppsFlyer.ForceCustomerUserId("your_customer_user_id");

[MRGSAppsFlyer forceCustomerUserId:@"your_customer_user_id"];

MRGSAppsFlyer#forceCustomerUserId("your_customer_user_id")

Задержка старта на iOS для ожидания ATT🔗

Также вы можете установить при настройке параметров при старте MRGS время в секундах, которое Appsflyer SDK должен подождать перед тем, как отправить событие установки/запуска. Необходимо для того, чтобы успеть получить IDFA пользователя на iOS 14+ при первой установке для последующей атрибуции. Подходит только для проектов, которые делают запрос разрешения IDFA сразу на старте. Учитывается только на iOS 14+, когда IDFA не получен. По умолчанию 0. Подробнее про данную функцию и необходимость ее использования/настройки читайте в официальной документации AppsFlyer.

appsFlyerParams.WaitForATTUserAuthorization = 10.0f;

appsFlyerParams.waitForATTUserAuthorization = 10.0f;

Шаг 3. Атрибуция приложений Android для нескольких магазинов🔗

Настройка атрибуции для приложений, доступных в нескольких магазинах Android. Вы можете объединить данные из всех магазинов приложений на одном дэшборде или использовать отдельный дэшборд для каждого магазина. Подробней

Шаг 4. Отслеживание платежей🔗

Клиент🔗

MRGS будет отправлять информацию о платеже в AppsFlyer, если выполнено одно из условий:

• Используется MRGSBilling для проведения платежей
• Используется MRGSMetrics для уведомления MRGS о платежах
• Используется Автотрекинг платежей на iOS

При отправке данных о платеже, MRGS передаст в AppsFlyer следующие события и данные:

Если по каким-то причинам вам нужно отключить отслеживание платежей, сделайте это в момент настройки и инициализации MRGS SDK:

sdkParams.AppsFlyerParams.DontForwardReportedPayments = true;

...
appsFlyerParams.dontForwardReportedPayments = YES;

[MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];

...
appsFlyerParams.setForwardPaymentsEnabled(false);
externalSDKParams.appsFlyerParams = appsFlyerParams;

MRGService.service(context, serviceParams, externalSDKParams);

Сервер🔗

По умолчанию, MRGS SDK отправляет события по платежам с клиента в AppsFlyer. Данный подход имеет существенный недостаток для подписок, а именно когда происходит ее продление, а пользователь не заходит в приложение. Поэтому, точность данных при отправке данных с клиента в AppsFlyer зависит от активности пользователя в приложении. MRGS сервер умеет следить за продлением подписок и может отправлять эту информацию в AppsFlyer.

Для включения данной возможности нужно:

• Получить projectId и devKey из AppsFlyer - документация.
• Включить отправку данных в AppsFlyer в MRGS консоли: Открыть ваш проект -> Интеграции -> AppsFlyer -> Отправлять данные в AppsFlyer.
• Добавить projectId и devKey из AppsFlyer в MRGS консоль.

Если на сервере включен механизм пересылки данных в Appsflyer (настраивается на сайте mrgs), то данные о доходах от рекламы, отправленные в унифицированных логах (или собранные автоматически с помощью модуля MRGSIronSource), будут пересылаться в AppsFlyer.

Шаг 5. Отслеживание событий из MRGSMetrics🔗

Для отслеживания событий из MRGSMetrics достаточно добавить настройку

...
sdkParams.AppsFlyerParams.ForwardMetrics = true;

...
appsFlyerParams.forwardMetrics = YES;

[MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];

...
appsFlyerParams.setForwardMetricsEnabled(true);
externalSDKParams.appsFlyerParams = appsFlyerParams;

MRGService.service(context, serviceParams, externalSDKParams);

Шаг 6. Проверка интеграции🔗

Мы рекомендуем проверять работу AppsFlyer с помощью механизма SDK Integration Tests, доступного на сайте AppsFlyer. По ссылке доступно руководство, как провести интеграционное тестирование.

Отправка событий🔗

Для работы с AppsFlyer воспользуйтесь объектом класса MRGSAppsFlyer:

MRGSAppsFlyer.Instance;

[MRGSAnalytics sharedInstance];

MRGSAnalytics.getInstance().getAppsFlyer();

С помощью этого API Вы сможете отправлять события в AppsFlyer напрямую. Например:

MRGSAppsFlyer.Instance.TrackEvent("someEvent", new Dictionary<string, object> { { "unity1", 1 }, { "unity2", "testUserInfo" } });

[[MRGSAnalytics sharedInstance] trackEvent:@"someEvent" eventParams:@{@"level":@"1"}];

Map params = new TreeMap();
params.put("androidParam", "androidValue");

MRGSAnalytics.getInstance().getAppsFlyer().sendEvent("someEvent", params);

При отправке любого события в AppsFlyer, MRGS автоматически обогатит его значениями mrgs_device_id и mrgs_user_id.

Получение данных о конверсиях🔗

Для получения данных о конверсиях Вам необходимо установить делегат, и реализовать его методы у себя в классе:

// Conforms to IMRGSAppsFlyerDelegate
MRGSAppsFlyer.Instance.Delegate = this;

// ...
public void OnConversionDataSuccess(Dictionary<string, object> conversionInfo)
{
    Debug.Log("OnConversionDataSuccess: \n" + MRGS.JSON.Json.Serialize(conversionInfo, true));
}
public void OnAppOpenAttribution(Dictionary<string, object> attributionData)
{
    Debug.Log("OnAppOpenAttribution: \n" + MRGS.JSON.Json.Serialize(attributionData, true));
}

[MRGSAnalytics sharedInstance].appsFlyer.delegate = self;
// ...
- (void)onAppOpenAttribution:(NSDictionary *)attributionData {
    NSLog(@"onAppOpenAttribution delegate called with data - %@", attributionData);
}
- (void)onConversionDataSuccess:(NSDictionary *)conversionInfo {
    NSLog(@"onConversionDataSuccess delegate called with data - %@", conversionInfo);
}

MRGSAnalytics.getInstance().getAppsFlyer().setConversionListener(this);//Где this - объект реализующий интерфейс MRGSAppsFlyerConversionListener
// ...
@Override
void onConversionDataSuccess(String jsonData) {
    MRGSLog.vp("onConversionDataSuccess " + jsonData);
}

@Override
void onAppOpenAttribution(String jsonData) {
    MRGSLog.vp("onAppOpenAttribution " + jsonData);
}

Структура словарей conversionInfo и attributionData описана на сайте AppsFlyer. Пример словаря:

{
    "af_message" = "organic install";
    "af_status" = Organic;
    "install_time" = "2019-12-25 16:00:03.115";
    "is_first_launch" = 0;
}

Получение AppsFlyerID🔗

Если Вам необходимо получить уникальный идентификатор AppsFlyer (appsFlyerID), воспользуйтесь следующим методом:

var aID = MRGSAppsFlyer.Instance.GetAppsFlyerId();

NSString* aID = [[MRGSAnalytics sharedInstance].appsFlyer getAppsFlyerId];

String aID = MRGSAnalytics.getInstance().getAppsFlyer().getAppsFlyerId();

Автоматические события🔗

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

Атрибуция приглашений пользователей🔗

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

Установка OneLink template ID🔗

Необходимо добавить его в настройки AppsFlyer при инициализации MRGService SDK, это единственный способ сделать это.

...
sdkParams.AppsFlyerParams.AppInviteOneLinkID = "your_invite_link_id";

...
appsFlyerParams.appInviteOneLinkID = @"your_invite_link_id";

[MRGService startWithServiceParams:<params> externalSDKParams:externalParams delegate:nil];

...
appsFlyerParams.setAppInviteOneLink("your_invite_link_id");
externalSDKParams.appsFlyerParams = appsFlyerParams;

MRGService.service(context, serviceParams, externalSDKParams);

Создание ссылки🔗

Для создания URL-адреса приглашения в соответствии с различными методами настройки, воспользуйтесь следующими методам из кода ниже. Для получения больше информации по методам, можно воспользоваться документацией

// Settings for link generation
var linkParams = new MRGSAppsFlyerLinkOptions
{
    Channel = "your_channel",
    Campaign = "your_campaign",
    ReferrerUID = "your_ref_id",
    ReferrerName = "your_ref_name",
    ReferrerImageURL = "your_ref_image",
    DeeplinkPath = "your_deep_link_path",
    BaseDeeplink = "your_base_deep_link",
    BrandDomain = "your_domain"
};
// If you need to add other custom fields.
linkParams.AddParameterValue("value", "custom_key");

// Link generation
MRGSAppsFlyer.Instance.GenerateUserInviteLink(linkParams, (link, error) =>
{
    Debug.Log("Did receive AppsFlyer invite link - " + link + "; with error - " + error);
});

// AppsFlyer invite link generation
MRGSAppsFlyerLinkOptions* linkParams = [[MRGSAppsFlyerLinkOptions alloc] init];
linkParams.channel = @"facebook";
linkParams.campaign = @"ad_campaign_id";
linkParams.referrerUID = [MRGSAnalytics sharedInstance].appsFlyer.customerUserID;
linkParams.referrerCustomerId = [MRGSAnalytics sharedInstance].appsFlyer.customerUserID;
linkParams.referrerName = @"Ivan Ivanov";
linkParams.referrerImageURL = nil;
linkParams.deeplinkPath = nil;
linkParams.baseDeeplink = nil;
linkParams.brandDomain = @"mrgs.astrum.team";
[linkParams addParameterValue:@"value" forKey:@"custom_key"];  

[[MRGSAnalytics sharedInstance].appsFlyer generateUserInviteLinkWithOptions:linkParams completionHandler:^(NSURL * _Nullable url, NSError * _Nullable linkGenerationError) {
    NSLog(@"Received AppsFlyer invite link - %@,  error - %@", url, linkGenerationError);
}];

import games.my.mrgs.analytics.MRGSAppsFlyerLinkGenerator;

MRGSAppsFlyerLinkGenerator.generateInviteUrl(Context)
        .setChannel("your_channel")
        .setCampaign("your_campaign")
        .setBrandDomain("your_domain")
        // Вызвать остальные методы по необходимости
        .generateLink(Context, new MRGSAppsFlyerLinkGenerator.ResponseListener() {
            @Override
            public void onResponse(String var1) {
                // handle link here
            }

            @Override
            public void onResponseError(String var1) {
                // handle error here
            }
        });