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

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

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

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

Содержание:

Добавление приложения;
Установка и интеграция SDK AppMetrica;
Настройка отправляемых из приложения событий;
Настройки панели 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. Настройка отправляемых из приложения событий

При интеграции через 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)
})

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

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

Подсказка

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

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

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

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

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

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

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

Блок «SmartLink»

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

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

Данный блок настроен по умолчанию. Сверьте ваши настройки с настройками на скриншоте:

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

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

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

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

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

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

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

Подсказка

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

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

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

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