Инструкция по настройке AppMetrica (постбеки)

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

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

Если у пользователя установлено мобильное приложение — мы будем отправлять его в приложение, после чего наша система будет атрибуцировать все его покупки.

Если у пользователя не установлено мобильное приложение — он будет как прежде совершать заказы на сайте по CPA-модели.

Важно понимать, что рекламодатель платит не за установки, а за конкретные покупки. Мы приводим и атрибуцируем каждую покупку за нужным партнером и вебмастером.

Примечание

AppMetrica также позволяет отслеживать установки не из магазина приложений – т.е. напрямую с сайта рекламодателя по клику на поп-ап сообщение «Скачать приложение/В приложении удобнее/Перейти в приложение» и т.д.

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

Содержание:

Добавление приложения;
Установка и интеграция SDK AppMetrica;
Настройка Universal Link;
Настройка отправляемых из приложения событий;
Настройки панели AppMetrica.
Проведение тестов.

Шаг 1. Добавление приложения

Перейдите на страницу добавления приложения;
Заполните параметры приложения: ссылка в магазине приложений (если приложение еще не опубликовано — оставьте поле пустым), название, часовой пояс для построения отчетов;
Скопируйте API-key;
Нажмите К обзору.

Шаг 2. Установка и интеграция SDK AppMetrica

Чтобы начать работать через AppMetrica необходимо интегрировать SDK AppMetrica в приложение.

Для Android

Установить SDK AppMetrica для Android можно двумя способами:

Через плагин (простой способ)

При установке через плагин, SDK AppMetrica установится и инициализируется сама, после этого нужно будет только настроить отправляемые из приложения события.

Чтобы добавить плагин AppMetrica:

Откройте менеджер плагинов в Android Studio («Preferences» → «Plugins»);
Найдите плагин AppMetrica, для этого в строке поиска введите «AppMetrica»;
Нажмите Install:

Плагин добавлен, теперь перейдем к установке SDK:

В главном меню выберите «Tools» → «AppMetrica» → «Integrate»;

Выберите приложение, в которое хотите добавить SDK:
- Скопируйте API-key из веб-интерфейса AppMetrica и вставьте в приложение (API-key можно найти здесь – https://appmetrica.yandex.ru/application/list);
- Выберите свое приложение из списка, после чего перейдите в настройки (ключ будет записан как API-key (для использования в SDK));
- Вставьте API-key в окно, открытое плагином.

Укажите настройки:
- First activation as update
Если в вашем приложении уже есть пользователи, тогда AppMetrica по умолчанию засчитает их за новых пользователей. Чтобы не учитывать текущую аудиторию новой, необходимо включить флаг firstActivationAsUpdate и указать условия, по которым пользователь будет учитываться как старый.
- Location tracking
С этой настройкой AppMetrica будет автоматически определять местоположение устройства и передавать эту информацию в отчеты и Logs API.
- Logs
Включает логирование работы библиотеки.
- Statistic sending
Включает/отключает отправку статистики на сервер AppMetrica. Например, если для отправки статистических данных требуется согласие пользователя.

Для последующего включения отправки статистики используйте метод YandexMetrica.setStatisticsSending(Context context, boolean enabled).
Нажмите OK, после чего библиотека будет добавлена и инициализирована.

Установка без плагина

Если вы используете Gradle, необходимо добавить следующую зависимость в build.gradle:

dependencies {
    implementation 'com.yandex.android:mobmetricalib:5.0.0'
}

Если вы не используете Gradle, необходимо скачать и добавить библиотеки ниже самостоятельно:

Инициализация библиотеки

Необходимо добавить следующий код в класс, производный от базового Application:

YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key).build();
YandexMetrica.activate(getApplicationContext(), config);
YandexMetrica.enableActivityAutoTracking(this);

В API_key необходимо вставить ключ, который мы ранее нашли в настройках приложения в веб-интерфейсе AppMetrica.

Пример:

Для iOS

Установить SDK AppMetrica для iOS можно тремя способами:

Через Cocoapods

Установите Сocoapods;
Подключите статическую или динамическую версию фреймворка. В зависимости от выбора, нужно добавить следующую строку в Podfile проекта:
- Статическая
pod 'YandexMobileMetrica', '4.2.0'
- Динамическая
pod 'YandexMobileMetrica/Dynamic', '4.2.0'

Через Carthage

Добавьте зависимость в Cartfile проекта:

binary "https://raw.githubusercontent.com/yandexmobile/metrica-sdk-ios/master/YandexMobileMetrica.json" ~> 4.2.0

Через SwiftPackageManager

Чтобы подключить библиотеку через SwiftPackageManager, выполните следующие действия:

В Xcode, в папке вашего проекта, выберите вкладку «Swift Packages» и нажмите +:

Укажите URL репозитория (https://github.com/yandexmobile/metrica-sdk-ios), в котором находится Swift-пакет:

Настройте правило для выбора версии пакета:

Выберите необходимые библиотеки и нажмите Add Package:

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

Загрузите библиотеку AppMetrica: https://storage.mds.yandex.net/get-appmetrica-mobile-sdk/50347/YandexMobileMetrica-4.2.0-ios-e34502a2-1cdd-4226-b575-86d35844b33c.zip;

Добавьте YandexMobileMetrica.framework в проект;

Для подключения обработки крэшей добавьте YandexMobileMetricaCrashes.framework (опционально);

Добавьте следующие зависимости: «SystemConfiguration», «UIKit», «Foundation», «CoreTelephony», «CoreLocation», «CoreGraphics», «AdSupport», «z», «sqlite3», «Security», «c++», «WebKit», «SafariServices» (с настройкой Optional);

Добавьте -ObjC в Other Linker Flags.

Инициализация SDK

Добавьте импорт:

import YandexMobileMetrica

Инициализируйте библиотеку в методе application(_:didFinishLaunchingWithOptions:) вашего UIApplicationDelegate:

let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API_key")
YMMYandexMetrica.activate(with: configuration!)

Подсказка

Вместо API_key необходимо вставить ваш ключ из веб-интерфейса AppMetrica.

Пример:

Шаг 3. Настройка Universal Link

Для iOS

Необходимо включить «Universal Link» в AppMetrica, для этого:

Выберите ваше приложение в шапке страницы;
На странице выбранного приложения перейдите в раздел Настройки:
На вкладке Основное спуститесь вниз страницы до блока «Universal Link»;
Введите «Bundle ID» и «App Prefix» приложения в соответствующие поля, установите переключатель «Использовать Universal Link» в положение «Вкл» и нажмите Сохранить настройки;
Теперь, в поле «Universal Link» появится ссылка вида applinks:<app_id>.redirect.appmetrica.yandex.com, где <app_id> — идентификатор вашего приложения в AppMetrica (ID приложения), скопируйте ее:

Подсказка

Как получить Bundle ID:

Значение Bundle ID можно найти в консоли разработчика Apple, в разделе «Organization Profile» → «Account Summary», а также в Xcode, в разделе «Target» → «Gen».

Как получить App Prefix:

Значение App Prefix можно найти в консоли разработчика Apple. В большинстве случаев App Prefix совпадает с Team ID. Этот идентификатор доступен также в консоли разработчика Apple (в разделе «Member Center» нажмите на свое имя в правом верхнем углу окна и выберите «View Account» → «Developer Account Summary»).

Для корректной работы «Universal Link» необходимо добавить в приложение следующие функции:

func application(_ application: UIApplication, handleOpenURL url: URL) -> Bool {
    return YMMYandexMetrica.handleOpen(url)
}

func application(_ application: UIApplication, openURL url: URL, sourceApplication: String?, annotation: AnyObject) -> Bool {
    return YMMYandexMetrica.handleOpen(url)
}

// Delegate for tracking Universal links.
func application(_ application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        if let url = userActivity.webpageURL {
            YMMYandexMetrica.handleOpen(url)
        }
    }
    return true
}

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

Нажмите на свой проект;
Нажмите на таргет проекта (показано на скриншоте снизу);
Перейдите на вкладку Capabilities;
Активируйте переключатель Associated domains;
Добавьте в список доменов новую ссылку с брендированным доменом. К ней нужно добавить префикс applinks, после чего ссылка будет выглядеть так: applinks:1234567.redirect.appmetrica.yandex.com, где 1234567 – ID вашего приложения в «AppMetrica»;

Для Android

Чтобы отслеживать открытия приложения с помощью DeepLink, нужно модифицировать активити, которое связано с DeepLink.

public class DeeplinkActivity extends Activity {

    @Override
    protected void onCreate(@Nullable final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        if (savedInstanceState == null) {
            YandexMetrica.reportAppOpen(this);
        }
    }
    @Override
    protected void onNewIntent(final Intent intent) {
        super.onNewIntent(intent);
        YandexMetrica.reportAppOpen(intent);
    }
}

Теперь необходимо добавить поддержку открытия ссылок через ваше приложение. В разделе для iOS мы настроили Universal Link и получили ссылку для нашего приложения. Необходимо добавить такую же ссылку в файл AnroidManifest.xml в следующем виде:

<data android:scheme="https"
    android:host="1234567.redirect.appmetrica.yandex.com"
    android:pathPrefix="/"
    />

Вместо 1234567 у вас будет ID вашего приложения в «AppMetrica». Например, ваш файл AnroidManifest.xml может выглядеть следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.advcake.getluckyapp">
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.GetLuckyApp">
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:label="@string/app_name"
            android:theme="@style/Theme.GetLuckyApp.NoActionBar">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter  android:autoVerify="false">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <!-- Начало добавленного кода -->
                <data android:scheme="https"
                    android:host="1234567.redirect.appmetrica.yandex.com"
                    android:pathPrefix="/"
                    />
                <!-- Конец добавленного кода -->
            </intent-filter>
        </activity>
    </application>
</manifest>

Шаг 4. Настройка отправляемых из приложения событий

При интеграции через AppMetrica, мы получаем информацию о заказе через значение отправленного события. Обязательные для нас параметры – «orderId» (ID заказа) и «price» (цена). Также, можно добавлять другие параметры, например, город или категорию.

Существует два типа подходящих событий – «purchase» (рекомендуется для покупок) и «event» (подходит, если вы отправляете постбеки не по покупкам или в других случаях).

Отправка на Android

Для начала вам необходимо создать объект Revenue с помощью метода newBuilderWithMicros().

Первый аргумент метода – цена, умноженная в 1000000 раз, второй аргумент – объект Currency, который можно получить с помощью метода getInstance().

События типа «purchase» отправляются с помощью reportRevenue().

Revenue revenue = Revenue.newBuilderWithMicros(99000000, Currency.getInstance("RUB"))
        .withProductID("com.yandex.service.299")
        .withQuantity(2)
        .withPayload("{\"OrderID\":\"Identifier\"}")
        .build();
YandexMetrica.getReporter(getApplicationContext(), "Testing API key").reportRevenue(revenue);

При отправке событий типа “purchase”, необходимо передать «orderId» в withPayload.

Любые другие события отправляются с помощью метода YandexMetrica.reportEvent(eventName, eventParameters), где «eventName» – имя события, а «eventParameters» – параметры события. Параметры могут быть JSON-строкой или объектом map.

Map<String, Object> eventParameters = new HashMap<String, Object>();
eventParameters.put("orderId", "123123123");
eventParameters.put("price", 480);

YandexMetrica.reportEvent("customEventName", eventParameters);

Отправка на iOS

Для начала необходимо получить revenueInfo с помощью класса YMMMutableRevenueInfo. Объект этого класса должен быть отправлен с помощью метода reportRevenue():

let price = NSDecimalNumber(string: "2100.5")
let revenueInfo = YMMMutableRevenueInfo.init(priceDecimal: price, currency: "BYN")

revenueInfo.productID = "TV soundbar"
revenueInfo.quantity = 2
revenueInfo.payload = ["OrderID": "Identifier"]

let reporter = YMMYandexMetrica.reporterForApiKey("API_key")
reporter.reportRevenue(revenueInfo, onFailure: { (error) in
    print("REPORT ERROR: \(error.localizedDescription)")
})

Здесь необходимо указать «OrderID» в payload.

Остальные события отправляются с помощью метода YMMYandexMetrica.reportEvent(eventName, parameters, onFailure), где «eventName» – имя события, «params» – параметры, а «onFailure» – блок, выполняемый при возникновении ошибки.

Параметры должны быть парами ключ-значение:

let params : [AnyHashable : Any] = ["orderId": "123123123", "price": 480]
YMMYandexMetrica.reportEvent("purchase", parameters: params, onFailure: { (error)
in
    print("DID FAIL REPORT EVENT: %@", message)
    print("REPORT ERROR: %@", error?.localizedDescription)
})

Нестандартная отправка событий

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

Шаг 5. Настройки панели AppMetrica

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

Предоставление доступа на чтение

Перейдите в раздел Настройки → вкладка Управление доступом;
Введите почту нашего пользователя – metrika@advcake.com в поле Аккаунт на Яндексе;
В поле Права доступа выберите «Только чтение»;
Нажмите Добавить:

Создание трекера

В разделе Трекинг нажмите Создать трекер:

Блок «Описание кампании»

Установите галочку на «Это ремаркетинговый трекер» и «Использовать SmartLink»;
Укажите название в формате “Appname_Advcake_Remarketing”, например “Mvideo_Advcake_Remarketing”;
Выберите ваше приложение из списка;
В поле партнер укажите «AdvCake»:

Блок «SmartLink»

В этом блоке настраиваются ссылки.

Целевая ссылка должна вести на веб-версию вашего приложения. Если у вас нет такой целевой ссылки, то её необходимо создать;
Обязательно добавьте Deeplink – он будет выглядеть как URI-схема вашего приложения:

Блок «Настройки атрибуции»

Установите галочку «Реатрибуция»:

Блок «Настройки постбеков»

Мы подготовили шаблоны для reengagament, установки, события и покупки:

Reengagement – Reeng advcake;
Установка – Install advcake;
Событие – Event advcake;
Покупка – Purcahse advcake.

Нажмите на кнопку + Добавить постбек (1), после чего выберите тип постбека (2), а затем получателя «AdvCake» (3).

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

После того, как вы выберите тип события и получателя, у вас появится список шаблонов – выберите соответствующие шаблоны для каждого типа постбеков (наименования указаны сверху).

Например, для типа постбека «Событие» (на скриншоте ниже) – нужно нажать на Event Advcake (4). Тогда в поле «Postback URL» автоматически подставится наш шаблон для кастомных событий.

Подсказка

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

Предупреждение

Уберите галочки с «Отправлять постбек только для первого целевого события» и «Отправлять постбеки install-партнеру», если они установлены:

После настройки постбеков, можно сохранять трекер. Теперь он готов к работе.

Шаг 6. Проведение тестов

После внесения всех правок в приложение и создания трекера можно приступить к тестированию интеграции.

Это поможет вам выявить и исправить допущенные ошибки.

Предварительно необходимо подготовить мобильные устройства для тестирования. Для этого, перейдите в раздел «Настройки» → «Управление доступом» и добавьте тестовые устройства.

Пролистайте страницу редактирования трекера вниз и скопируйте ссылку «Tracking URL for apps»:

Удалите из ссылки все параметры, кроме appmetrica_tracking_id и referrer;
Добавьте в ссылку параметры afpub_id=affiliate, site_id=test и click_id (случайное число).

Пример измененной ссылки:

https://1234567.redirect.appmetrica.yandex.com/?appmetrica_tracking_id=2415974239893120&referrer=reattribution%3D1&afpub_id=affiliate&site_id=test&click_id=00001

Подсказка

Параметр click_id должен быть уникальным значением. Это значит, что после каждого перехода по ссылке нужно заменять click_id на другое значение.

Перейдите по ссылке с ПК, после чего у вас должна открыться веб-версия вашего приложения. Если этого не произошло – проверьте настройки трекера;
Отправьте ссылку на мобильные устройства для тестирования. Не забудьте изменить click_id в ваших ссылках;
Удалите приложения с мобильных устройств и перейдите по ссылке. Если после перехода открылась веб-версия вашего приложения – это значит, что всё настроено правильно. В противном случае, перепроверьте настройки трекера;
Установите приложения на мобильные устройства и перейдите по ссылке. Ваши приложения должны перехватывать ссылки и открывать их изнутри. Если этого не происходит – проверьте, все ли правки вы внесли в приложение (AndroidManifest.xml / Associated domains);
Перейдите по новой ссылке и совершите тестовую покупку в приложении. Должен выполниться код, который вы настраивали ранее.

Как узнать приходят ли события покупок

Узнать приходят ли события покупок можно двумя способами:

Перейдите в раздел Отчеты → События (1) и сегментируйте отчет по пользователям, у которых Reengagement → партнер: AdvCake (2);
Если события отображаются в общем фильтре, но не отображаются в фильтре с Reengagement и нашим партнером – проверьте, внедрили ли вы код, позволяющий отслеживать открытия с помощью Deeplink;
Если события вообще не отображаются – проверьте, добавили ли вы код, который отправляет события:

Примечание

Обратите внимание, обычно события подгружаются в течение часа.

Перейдите в раздел разделе Отчёты → Revenue:

После успешной передачи события покупки значение «Total Revenue» за текущий день изменится, что можно увидеть на графике и в таблице под ним:

Для того, чтобы увидеть конкретное событие покупки, нужно выполнить экспорт данных в разделе Экспорт данных → Сохранить в файл:

Здесь нужно выбрать вкладку События, указать нужный период, отметить поля для выгрузки и нажать на кнопку Скачать файл:

В полученном файле в колонке «event_name» можно найти нужное название события (обычно это af_purchase), а в колонке «event_json» - номер заказа: