Carrot quest SDK

Тема

Запись событий ​

Убедитесь, что предыдущие шаги выполнены успешно
  • SDK добавлено в ваше мобильное приложение (в проекте появилась зависимость CarrotSDK)
  • Ключи взяты из раздела для разработчика (не из webApi): ключи для SDK
  • Инициализация выполнена успешно и приложение запустилось без ошибок
  • В консоли появилась надпись “SDK init success”
Результат шага
  • События добавляются в карточку пользователя и отображаются корректно

Метод отправки событий ​

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

swift
import CarrotSDK

Carrot.shared.trackEvent(withName: "eventName", withParams: "")
objective-c
#import "CarrotSDK/CarrotSDK.h"

Carrot *carrot = [Carrot shared];
[
  carrot
  trackEventWithName: name
  withParams: params
];

Обратите внимание, что параметры события передаются в виде строки, внутри у которой должен быть JSON. Примерно вот так:

swift
import CarrotSDK

let strJSON: String = #"{"Приложение": "iOS"}"#
Carrot.shared.trackEvent(withName: "eventName", withParams: strJSON)
objective-c
#import "CarrotSDK/CarrotSDK.h"

NSString *strJSON = @"{\"Приложение\": \"iOS\"}";
[[Carrot shared] trackEventWithName:@"eventName" withParams:strJSON];

Трекинг экранов ​

Для запуска триггерных сообщений на определенных экранах можно передавать названия экранов через trackScreen():

swift
import CarrotSDK

let screenName: String = "CatalogScreen"
Carrot.shared.trackScreen(screenName)
objective-c
#import "CarrotSDK/CarrotSDK.h"

Carrot *carrot = [Carrot shared];
[carrot trackScreen:@"CatalogScreen"];

Трекинг UTM-меток ​

Метод trackUtm извлекает UTM-параметры из строки запроса переданного URL и фиксирует их как события и свойства пользователя. Типичный сценарий — вызов при открытии приложения через Universal Link (диплинк) или URL scheme. Однако, метод можно вызвать откуда угодно, он принимает сразу тип URL:

swift
import CarrotSDK

Carrot.shared.trackUtm(url)
objective-c
#import "CarrotSDK/CarrotSDK.h"

[[Carrot shared] trackUtm:url];

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

AppDelegate ​

Для приложений без SceneDelegate обработайте URL Scheme в AppDelegate:

swift
import CarrotSDK

extension AppDelegate {
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any]) -> Bool {
        Carrot.shared.trackUtm(url)
        return true
    }
}
objective-c
#import <CarrotSDK/CarrotSDK-Swift.h>

@implementation AppDelegate

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

@end

Для Universal Link (диплинк) используйте continue userActivity:

swift
import CarrotSDK

extension AppDelegate {
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let url = userActivity.webpageURL else {
            return false
        }

        Carrot.shared.trackUtm(url)
        return true
    }
}
objective-c
#import <CarrotSDK/CarrotSDK-Swift.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb] &&
        userActivity.webpageURL != nil) {
        [[Carrot shared] trackUtm:userActivity.webpageURL];
        return YES;
    }

    return NO;
}

@end

SceneDelegate ​

Если в приложении используется SceneDelegate, URL Scheme нужно обрабатывать в нем. В этом случае метод application(_:open:options:) из AppDelegate может не вызваться.

swift
import CarrotSDK

extension SceneDelegate {
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else {
            return
        }

        Carrot.shared.trackUtm(url)
    }
}
objective-c
#import <CarrotSDK/CarrotSDK-Swift.h>

@implementation SceneDelegate

- (void)scene:(UIScene *)scene
openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    NSURL *url = URLContexts.allObjects.firstObject.URL;

    if (url != nil) {
        [[Carrot shared] trackUtm:url];
    }
}

@end

Для Universal Link (диплинк) в SceneDelegate используйте continue userActivity:

swift
import CarrotSDK

extension SceneDelegate {
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let url = userActivity.webpageURL else {
            return
        }

        Carrot.shared.trackUtm(url)
    }
}
objective-c
#import <CarrotSDK/CarrotSDK-Swift.h>

@implementation SceneDelegate

- (void)scene:(UIScene *)scene
continueUserActivity:(NSUserActivity *)userActivity {
    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb] &&
        userActivity.webpageURL != nil) {
        [[Carrot shared] trackUtm:userActivity.webpageURL];
    }
}

@end

SwiftUI WindowGroup ​

В приложениях со SwiftUI lifecycle URL Scheme обычно обрабатывается через .onOpenURL:

swift
import SwiftUI
import CarrotSDK

@main
struct ExampleApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    Carrot.shared.trackUtm(url)
                }
        }
    }
}

Для Universal Link в SwiftUI используйте .onContinueUserActivity:

swift
import SwiftUI
import CarrotSDK

@main
struct ExampleApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { userActivity in
                    guard let url = userActivity.webpageURL else {
                        return
                    }

                    Carrot.shared.trackUtm(url)
                }
        }
    }
}

SwiftUI lifecycle недоступен для приложений, полностью написанных на Objective-C. Для таких проектов используйте AppDelegate или SceneDelegate.

Проверить URL Scheme на симуляторе можно командой:

bash
xcrun simctl openurl booted "example://open?utm_source=test&utm_medium=app&utm_campaign=demo"

Кейсы ​

Какие примеры событий могут быть и как их настроить:

Запись события входа в приложение ​

Событие входа в приложение. Например, в AppDelegate, в функции открытия приложения, можно повесить запись события. Главное убедиться, что сам SDK инициализируется раньше:

swift
import CarrotSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {

		func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
				...
				Carrot.shared.setup(
            withApiKey: apiKey,
            successHandler: { 
							Carrot.shared.trackEvent(withName: "Зашел в приложение", withParams: "")	      
						},
            errorHandler: { _ in }
        )
				
				return true
    }
}
objective-c
#import "CarrotSDK/CarrotSDK.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[Carrot shared] setupWithApiKey:apiKey
                      successHandler:^{
                          [[Carrot shared] trackEventWithName:@"Зашел в приложение" withParams:@""];
                      }
                        errorHandler:^(NSString *error) {
                        }];

    return YES;
}

Запись события отписки от пушей ​

swift
import CarrotSDK

CarrotNotificationService.shared.pushNotificationsUnsubscribe()

let strJSON = #"{"Пользователь": "\(userId)"}"#
Carrot.shared.trackEvent(withName: "Отписался от пушей", withParams: strJSON)
objective-c
#import "CarrotSDK/CarrotSDK.h"

[[CarrotNotificationService shared] pushNotificationsUnsubscribe];

NSString *strJSON = [NSString stringWithFormat:@"{\"Пользователь\": \"%@\"}", userId];
[[Carrot shared] trackEventWithName:@"Отписался от пушей" withParams:strJSON];

Методы WebAPI ​

Если у вас возникли вопросы, вы можете посмотреть, как похожая механика работает в методах WebAPI, можно найти по ссылке: https://developers.carrotquest.io/webapi/endpoints/