iOS

Подключите MyTracker SDK для iOS. В качестве примера вы можете использовать готовые демо-приложения на Objective-C и Swift.

Минимальные требования

Минимальная поддерживаемая версия iOS — 9.0, начиная с версии SDK 2.1.0 от 9 сентября 2020.

Интеграция

Подключение с использованием CocoaPods

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

pod 'myTrackerSDK'

Запустите pod install.

Подключение с использованием Swift Package Manager

  1. В вашем проекте через меню File → Swift Packages → Add Package Dependency... откройте окно добавления зависимости.
  2. Выберите таргет, к которому нужно добавить SDK. Если в вашем проекте один таргет, он будет выбран автоматически.
  3. В поле Enter package repository URL введите адрес репозитория MyTracker SDK: https://github.com/myTrackerSDK/mytracker-ios-spm. XCode предложит выбрать версию SDK, по умолчанию будет использоваться последняя версия.
  4. Нажмите Next. MyTracker SDK будет добавлен как зависимость к вашему проекту.

Из-за некоторых ограничений на стороне Swift Package Manager, после добавления MyTracker SDK необходимо вручную добавить к таргету приложения фреймворк AdServices:

  1. Выберите файл проекта в навигаторе XCode, в списке Targets выберите ваше приложение.
  2. Перейдите на вкладку Build Phases и в список Link Binary With Libraries добавьте AdServices.framework. После добавления не забудьте установить Status в Optional.

Вручную

  1. Скачайте последнюю версию MyTracker iOS SDK и распакуйте архив.

  2. Подключите в проект фреймворк MyTrackerSDK.framework из распакованного архива.

  3. Подключите к проекту фреймворки UIKit, AdSupport, SystemConfiguration, CoreTelephony, CoreData, iAd, StoreKit, AdServices.

  4. Подключите к проекту библиотеку libz.tbd.

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

Для корректной работы MyTracker SDK настройку и инициализацию трекера необходимо производить в классе AppDelegate вашего приложения, в методе application:didFinishLaunchingWithOptions. Для инициализации трекера необходимо указать ваш SDK_KEY, но перед этим следует выполнить необходимые настройки (конфигурации, трекинга пользователей, диплинков и пр.).

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

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    //  При необходимости, настройте конфигурацию трекера
    MRMyTrackerConfig *trackerConfig = [MRMyTracker trackerConfig];
    // …
    // Настройте параметры трекера
    // …
    // Инициализируйте трекер
    [MRMyTracker setupTracker:SDK_KEY];

   return YES;
}

@end
import MyTrackerSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool
{

    // При необходимости, настройте конфигурацию трекера
    let trackerConfig = MRMyTracker.trackerConfig()
    // ...
    // Настройте параметры трекера
    // ...
    // Инициализируйте трекер
    MRMyTracker.setupTracker(SDK_KEY)

    return true
}        

API

Конфигурация трекера

Конфигурацию трекера можно настроить через экземпляр класса MRMyTrackerConfig, доступный через метод [MRMyTracker trackerConfig]. Можно настраивать следующие параметры:

trackLaunch: отслеживание запусков приложения. По умолчанию YES.

@property(nonatomic) BOOL trackLaunch;
var trackLaunch: Bool

launchTimeout: интервал в секундах, в течение которого не будет засчитываться новый запуск и прерываться сессия при сворачивании приложения. По умолчанию 30 секунд. Можно установить значение в диапазоне 30-7200 секунд.

@property(nonatomic) NSTimeInterval launchTimeout;
var launchTimeout: NSTimeInterval

bufferingPeriod: интервал в секундах, в течение которого события будут накапливаться на устройстве перед отправкой на сервер. По умолчанию 900 секунд. Можно установить значение в диапазоне 1-86400 секунд (1 день).

@property(nonatomic) NSTimeInterval bufferingPeriod;
var bufferingPeriod: NSTimeInterval

forcingPeriod: интервал в секундах после установки или обновления приложения, в течение которого события будут незамедлительно отправляться на сервер без локальной буферизации. По умолчанию 0 секунд (незамедлительная отправка выключена). Можно установить значение в диапазоне 0-432000 секунд (5 суток).

@property(nonatomic) NSTimeInterval forcingPeriod;
var forcingPeriod: NSTimeInterval

autotrackPurchase: автоматическое отслеживание покупок в приложении. По умолчанию YES.

@property(nonatomic) BOOL autotrackPurchase;
var autotrackPurchase: Bool

locationTrackingMode: отслеживание местоположения пользователя. Доступные значения:

  • MRLocationTrackingModeNone — отслеживание местоположения не производится

  • MRLocationTrackingModeCached — используется закэшированное системой значение

  • MRLocationTrackingModeActive — используется запрос текущего местоположения (по умолчанию)

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

@property(nonatomic) MRLocationTrackingMode locationTrackingMode;
var locationTrackingMode: MRLocationTrackingMode

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

  • MRRegionNotSet — значение по умолчанию

  • MRRegionRu — сервер, расположенный на территории Российской Федерации

  • MRRegionEu — сервер, расположенный на территории Европы

@property(nonatomic) MRRegion region
var region: MRRegion

registerForSKAdAttribution: поддержка SKAdNetwork атрибуции. По умолчанию YES.

SKAdNetwork — это инструмент атрибуции от Apple, который позволяет связать установку приложения с рекламной кампанией, и при этом сохранить конфиденциальность пользователей.

По умолчанию при первом запуске приложения на устройствах iOS 14.5+, MyTracker SDK версии 2.1.2 и выше вызовет метод SKAdNetwork — registerAppForAdNetworkAttribution, чтобы передать в рекламную сеть информацию о связанной установке. Рекламная сеть в свою очередь может отправить данные в MyTracker. С версии iOS 15 копию данных можно отправить напрямую в MyTracker, без посредничества рекламных сетей.

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

Подробнее см. раздел iOS и SKAdNetwork и документацию Apple

@property(nonatomic) BOOL registerForSKAdAttribution;
var registerForSKAdAttribution: Bool

Вкл/выкл режима отладки

Включение/выключение режима отладки производится через статические методы класса MRMyTracker. По умолчанию false.

+ (void)setDebugMode:(BOOL)enabled;
+ (BOOL)isDebugMode;
static func setDebugMode(_ enabled: Bool)static func isDebugMode() -> Bool

Трекинг пользователей

Для отслеживания статистики не только по устройствам, но и по пользователям, установите параметр customUserId. Это уникальный идентификатор пользователя в вашем проекте, который вы присваиваете ему в момент регистрации. Он должен оставаться неизменным, даже если пользователь авторизуется на другом устройстве. Установив этот параметр, вы сможете оценить размер и активность аудитории приложения, вне зависимости от того, на скольких устройствах пользователя установлено ваше приложение. А также не будете терять историю накопленных по пользователю данных, если он решит сменить устройство. Подробнее см. раздел Трекинг.

Параметры трекера можно настроить через экземпляр класса MRMyTrackerParams, доступный через метод [MRMyTracker trackerParams]. Важно установить параметр до трекинга событий, чтобы передавать идентификатор пользователя с каждым отслеженным событием.

-(void)setUserInfo
{
    MRMyTrackerParams *trackerParams = [MRMyTracker trackerParams];

    // Установите пользовательский идентификатор
    trackerParams.customUserId = @"user_id";

}
func setUserInfo()
{
    let trackerParams = MRMyTracker.trackerParams()

    // Установите пользовательский идентификатор
    trackerParams.customUserId = "user_id"
}

Если до установки customUserId в приложении уже сформирована база зарегистрированных пользователей, то MyTracker не сможет получить данные о времени их регистрации и произвести точный расчёт Lifetime метрик. Для таких пользователей Lifetime статистика будет считаться на дату первого отслеженного события с customUserId.

Чтобы отключить трекинг пользователей передайте пустое значение в параметре customUserId.

Трекинг событий

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

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

Событие регистрации. Метод должен быть вызван сразу после того, как пользователь зарегистрируется в приложении. Идентификатор пользователя должен быть передан в параметре userId.

Идентификатор userId — обязательный параметр начиная с SDK версии 2.0.6

+ (void)trackRegistrationEvent:(NSString *)userId;
static func trackRegistrationEvent(userId: String) 

Событие авторизации. Метод должен быть вызван сразу после того, как пользователь успешно авторизуется в приложении. Идентификатор пользователя должен быть передан в параметре userId.

Идентификатор userId — обязательный параметр начиная с SDK версии 2.0.6

+ (void)trackLoginEvent:(NSString *)userId;
static func trackLoginEvent(userId: String)

Событие отправки приглашения. Дополнительный параметр eventParams позволяет задать произвольные параметры ключ-значение для события. Максимальная длина ключа и значения — 255 символов.

+ (void)trackInviteEvent;
+ (void)trackInviteEventWithParams:(NSDictionary<NSString *, NSString *>*)eventParams;
static func trackInviteEvent()
static func trackInviteEvent(eventParams: [String: String]?)

Событие достижения уровня. Можно отправлять как с указанием номера уровня (параметр level), так и без. Дополнительный параметр eventParams позволяет задать произвольные параметры ключ-значение для события. Максимальная длина ключа и значения — 255 символов.

+ (void)trackLevelAchieved;
+ (void)trackLevelAchievedWithLevel:(NSNumber *)level;
+ (void)trackLevelAchievedWithLevel:(NSNumber *)level eventParams:(NSDictionary<NSString*, NSString *> *)eventParams;
static func trackLevelAchieved()
static func trackLevelAchieved(level: NSNumber?)
static func trackLevelAchieved(level: NSNumber?, eventParams:[String: String]?)

Произвольное событие с заданным именем. Дополнительный параметр eventParams позволяет задать произвольные параметры ключ-значение для события. Максимальная длина имени, ключа и значения — 255 символов.

+ (void)trackEventWithName:(NSString *)name;
+ (void)trackEventWithName:(NSString *)name eventParams:(NSDictionary<NSString*, NSString *> *)eventParams;
static func trackEvent(name: NSString)
static func trackEvent(name: NSString, eventParams: [String: String]?)

Пример:

NSDictionary *eventCustomParams = @{
    @"someParamKey1" : @"someParamValue1",
    @"someParamKey2" : @"someParamValue2"
  };
[MRMyTracker trackEventWithName:@"eventName" eventParams:eventCustomParams];
let eventCustomParams = ["someParamKey1": "someParamValue1",
                         "someParamKey2": "someParamValue2"]
MRMyTracker.trackEvent(name: "eventName", eventParams:eventCustomParams)

Принудительная отправка всех событий и сброс таймера отправки.

SDK для снижения нагрузки на канал и минимизации влияния на производительность приложения накапливает в буфер все события на устройстве перед отправкой на сервер и регулярно отправляет собранные данные сжатым пакетом. По умолчанию данные отправляются на сервер каждые 15 минут. Этот интервал можно настроить через параметр bufferingPeriod от 1 секунды до 1 суток. Если пользователь закрыл приложение, то отправка будет произведена при следующем запуске. Но некоторые события крайне важно получать в аналитику как можно раньше, особенно в первые сессии после установки приложения. В этом поможет метод flush().

+ (void)flush;
static func flush()

Трекинг встроенных покупок

Все встроенные покупки в приложении отслеживаются автоматически.

Если вы хотите отслеживать покупки вручную, необходимо выключить автоматический трекинг покупок параметром autotrackPurchase = NO, и воспользоваться методами:

+ (void)trackPurchaseWithProduct:(SKProduct *)product transaction:(SKPaymentTransaction *)transaction;
+ (void)trackPurchaseWithProduct:(SKProduct *)product transaction:(SKPaymentTransaction *)transaction eventParams:(NSDictionary<NSString *, NSString *> *)eventParams;
static func trackPurchase(product: SKProduct, transaction: SKPaymentTransaction)
static func trackPurchase(product: SKProduct, transaction: SKPaymentTransaction, eventParams: [String: String]?)

При включенном автоматическом трекинге покупок вызовы этих методов игнорируются. Обязательные параметры:

Дополнительный параметр eventParams позволяет задать произвольные параметры ключ-значение для события. Максимальная длина ключа и значения — 255 символов.


S2S трекинг

Для передачи данных с вашего сервера на сервер MyTracker (например, неотслеживаемых данных, офлайн-событий и пр.), может понадобиться специальный идентификатор устройства — instanceId. Идентификатор представляет собой значение UUID v4, которое генерируется в момент первого запуска приложения и остаётся неизменным до удаления приложения (или данных приложения) с устройства.

Получить instanceId можно с помощью статического метода класса MRMyTracker (не следует использовать этот метод на главном потоке).

+ (NSString *)instanceId;
static let instanceId: String

Важно как можно раньше начать собирать instanceId и отправлять на ваш сервер, если вы используете его для передачи данных к S2S API.

Вместо instanceId в запросах к API можно указывать любой другой идентификатор устройства: idfa, iosVendorId, и/или идентификатор пользователя customUserID (в этом случае данные будут формировать статистику по пользователю). Подробнее

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

Для поддержки обычных и отложенных диплинков в своем приложении вам необходимо установить делегат, реализующий протокол MRMyTrackerAttributionDelegate. Делегат будет вызван при первом запуске приложения в случае, если для текущей установки был найден отложенный диплинк, а также каждый раз при запуске приложения по диплинку. В качестве параметра в метод didReceiveAttribution будет передан объект атрибуции MRMyTrackerAttribution, содержащий свойство deeplink.

@interface AppDelegate () <MRMyTrackerAttributionDelegate>
@end


@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    //  При необходимости, настройте конфигурацию трекера
    MRMyTrackerConfig *trackerConfig = [MRMyTracker trackerConfig];
    // …
    // Настройте параметры трекера
    // …

    // Установите делегат для получения отложенного диплинка
    [MRMyTracker setAttributionDelegate:self];

    // Инициализируйте трекер
    [MRMyTracker setupTracker:SDK_KEY];

   return YES;
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(nullable NSString *)sourceApplication annotation:(id)annotation
{
    return [MRMyTracker handleOpenURL:url sourceApplication:sourceApplication annotation:annotation];
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
{
    return [MRMyTracker handleOpenURL:url options:options];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray * __nullable restorableObjects))restorationHandler
{
    return [MRMyTracker continueUserActivity:userActivity restorationHandler:restorationHandler];
}

#pragma mark - MRMyTrackerAttributionDelegate


- (void)didReceiveAttribution:(MRMyTrackerAttribution *)attribution
{
    NSString *deeplink = attribution.deeplink;
    // Обработка диплинка
    // ...
}

@end
import MyTrackerSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, MRMyTrackerAttributionDelegate
{
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool
    {
        // При необходимости, настройте конфигурацию трекера
        let trackerConfig = MRMyTracker.trackerConfig()
        // ...
        // Настройте параметры трекера
        // ...

        // Установите делегат для получения отложенного диплинка
        MRMyTracker.setAttributionDelegate(self)

        // Инициализируйте трекер
        MRMyTracker.setupTracker(SDK_KEY)

        return true
    }

    func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool
    {
        return MRMyTracker.handleOpen(url, sourceApplication: sourceApplication, annotation: annotation)
    }

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool
    {
        return MRMyTracker.handleOpen(url, options: options)
    }

    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool
    {
        let handler: ([Any]?) -> Void = {_ in }
        return MRMyTracker.continue(userActivity, restorationHandler: handler)
    }

    // MARK: MRMyTrackerAttributionDelegate

    func didReceive(attribution: MRMyTrackerAttribution)
    {
        let deeplink = attribution.deeplink

        // Обработка диплинка
        // ...
    }
}

При желании, при установке делегата вы можете задать очередь NSOperationQueue выполнения методов делегата c помощью метода setAttributionDelegate:delegateQueue. Если при установке делегата не задана очередь исполнения метод didReceiveAttribution будет вызван в главном потоке.