pod 'myTrackerSDK'
Подключите MyTracker SDK для iOS. В качестве примера вы можете использовать готовые демо-приложения на Objective-C и Swift.
Минимальная поддерживаемая версия iOS — 12.4, начиная с версии SDK 3.1.0 от 16 октября 2023.
Добавьте в ваш Podfile зависимость:
pod 'myTrackerSDK'
Запустите pod install.
https://github.com/myTrackerSDK/mytracker-ios-spm
.
XCode предложит выбрать версию SDK,
по умолчанию будет использоваться последняя версия.
'-ObjC'
в Other Linker Flags на вкладке Build Settings вашего проекта.Из-за некоторых ограничений на стороне Swift Package Manager, после добавления MyTracker SDK необходимо вручную добавить к таргету приложения фреймворк AdServices:
Скачайте последнюю версию MyTracker iOS SDK и распакуйте архив.
Подключите в проект фреймворк MyTrackerSDK.framework из распакованного архива.
Подключите к проекту фреймворки UIKit, AdSupport, SystemConfiguration, CoreTelephony, CoreData, StoreKit, AdServices, and AppTrackingTransparency.
Подключите к проекту библиотеку 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
}
Конфигурацию трекера можно настроить через экземпляр класса 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: регион, где расположен сервер сбора статистики.
С 1 марта 2023г. параметр 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
Вы можете создать свою реализацию Logger, чтобы получать логи MyTracker SDK не только в консоли, но и в вашем коде.
Для этого используйте статические методы класса MRMyTracker
.
+ (void)setCustomLogger:(nullable id <MRLogger>)customLogger;
+ (nullable id <MRLogger>)customLogger;
static func setCustomLogger(_ customLogger: Logger?)
static func customLogger() -> Logger?
Для получения статистики не только по устройствам, но и по пользователям, установите параметр 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()
Чтобы контролировать результат принудительной отправки,
вместе с методом flush()
используйте параметр Completion
.
Если события отправились или нет событий для отправки, то в логе будет
Flush complete, success: 1
,
если события по каким-то причинам не получилось отправить, то
Flush complete, success: 0
.
+ (void)flushWithCompletionBlock:(void (^)(BOOL success))completionBlock;
static func flush(completion: (Bool) -> Void)
Сбор данных по in-app платежам и подпискам происходит автоматически.
Если вы хотите собирать данные о платежах вручную, необходимо выключить автоматический трекинг
параметром 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]?)
При включенном автоматическом трекинге платежей вызовы этих методов игнорируются. Обязательные параметры:
product
- объект класса SKProduct, полученный для платежа
transaction
- объект класса SKPaymentTransaction,полученный для
платежа
Дополнительный параметр eventParams
позволяет задать произвольные параметры ключ-значение
для события. Максимальная длина ключа и значения — 255 символов.
Для передачи данных с вашего сервера на сервер 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
будет вызван в главном потоке.