Настройка и подключение SDK

Для работы с In-App-каналом в мобильное приложение необходимо интегрировать Altcraft mSDK. SDK отвечает за аутентификацию пользователя, подписку на канал, получение доступных размещений и показ In-App-контента в приложении.

Подключение mSDK

Процедура подключения mSDK зависит от платформы. Подробные инструкции по каждой платформе предоставлены в руководстве разработчика: Android, iOS, Flutter, React Native.

Авторизация

SDK поддерживает два способа авторизации — JWT-токен и ролевой токен (rToken):

• JWT-токен — обязателен, если нужна персонализация. Матчинг профиля (поиск по email, телефону, profile_id и другим идентификаторам) возможен только с JWT. JWT-провайдер регистрируется в SDK до инициализации.
• rToken — ролевой токен, привязанный к ресурсу. In-App не привязан к push-каналу: ролевой токен можно использовать и без интеграции push-провайдеров. Но с ролевым токеном размещения запускаются для всех пользователей — персонализация недоступна.

После создания ресурса в его настройках будет доступен раздел с управлением токенами:

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

Ролевой токен выступает ключом доступа со стороны mSDK к связке «ресурс-база».

Для создания JWT-токена понадобится предоставить публичный ключ. Платформа допускает использование алгоритма ES384 (ECDSA, как наиболее надёжный), а также RS256, ES256, ES512 для совместимости с библиотеками разных приложений:

Приложение должно передать SDK JWT-токен, который генерируется серверной частью клиента с помощью следующего payload:

{
  "iss": "<App Name>",
  "exp": <UnixTimeUTC>,
  "rtoken": "<RoleToken>",
  "matching": "JSONString"
}

• iss — issuer — уникальный идентификатор создателя токена;
• exp — expiration time — время истечения токена в формате UNIX timestamp в секундах;
• rtoken — ролевой токен, полученный при настройке ресурса в платформе;
• matching — сериализованный в строку объект матчинга профиля, например {"db_id":2,"email":"registered_db@localhost","matching":"email_profile"}.

Подробнее о структуре JWT и его отличиях от rToken — в статье Работа с ролевым и JWT-токеном.

Инициализация и запуск In-App

Базовый принцип работы с SDK:

1. Интегрируйте mSDK и настройте авторизацию (см. выше).
2. При старте приложения инициализируйте SDK: укажите API-адрес платформы, при JWT-авторизации зарегистрируйте провайдер токена до инициализации.
3. Сразу после инициализации подпишитесь на жизненный цикл активности (registerLifecycleTracking()), иначе In-App-уведомления, которые должны показаться при старте приложения, могут быть пропущены.
4. После инициализации выполните в приложении: аутентификацию (authenticate()), подписку на канал (inAppSubscribe()), запрос размещений (getInAppPlacements()). Для показа контента только на определённых экранах используйте setScreen().

Обязательно вызывайте inAppSubscribe()

Даже если подписка на In-App-канал добавлена вручную в интерфейсе платформы, необходимо вызвать inAppSubscribe() в приложении. Без этого SDK не зарегистрирует профиль для In-App, матчинг не сработает, и персонализированные размещения не будут показываться. Функцию вызывайте после завершения аутентификации.

Пример инициализации и подписки (Android)

Инициализация в классе приложения:

class AltcraftApp : Application() {
    override fun onCreate() {
        super.onCreate()

        // Регистрация JWT-провайдера (до инициализации SDK)
        AltcraftSDK.setJWTProvider(MyJWTProvider())

        // Инициализация SDK
        val config = AltcraftConfiguration.Builder(
            apiUrl = "https://<API-домен>",
            enableLogging = true
        ).build()
        AltcraftSDK.initialization(context = this, configuration = config)

        // Регистрация жизненного цикла активности для автоматического показа In-App
        AltcraftSDK.inAppFunctions.registerLifecycleTracking(this)
    }
}

Аутентификация, подписка и запрос размещений в активности:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Устанавливаем экран для фильтрации In-App-контента
        AltcraftSDK.inAppFunctions.setScreen("home")

        // Запрос доступных размещений In-App
        AltcraftSDK.inAppFunctions.getInAppPlacements(this)

        // Аутентификация и подписка на In-App-канал
        CoroutineScope(Dispatchers.Main).launch {
            AltcraftSDK.authFunctions.authenticate(this@MainActivity)
            withTimeoutOrNull(10_000L) {
                while (!AltcraftSDK.authFunctions.isAuthenticated(this@MainActivity)) {
                    delay(100L)
                }
            }
            AltcraftSDK.inAppFunctions.inAppSubscribe(context = this@MainActivity, sync = true)
        }
    }
}

Пример инициализации и подписки (iOS)

Инициализация в AppDelegate.application(_:didFinishLaunchingWithOptions:):

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Регистрация JWT-провайдера (до инициализации SDK)
        AltcraftSDK.setJWTProvider(provider: JWTProvider())

        // Инициализация SDK
        AltcraftSDK.shared.initialization()

        // Регистрация жизненного цикла приложения для автоматического показа In-App
        AltcraftSDK.shared.inAppFunctions.registerLifecycleTracking()

        return true
    }
}

Аутентификация, подписка и запрос размещений:

// Устанавливаем экран для фильтрации In-App-контента
AltcraftSDK.shared.inAppFunctions.setScreen(screen: "home")

// Запрос доступных размещений In-App
AltcraftSDK.shared.inAppFunctions.getInAppPlacements()

// Аутентификация и подписка на In-App-канал
AltcraftSDK.shared.authFunctions.authenticate()
AltcraftSDK.shared.inAppFunctions.inAppSubscribe()

Подробные примеры кода для каждой платформы — в документации по mSDK.

Особенности и частые ошибки

• Неверный API-домен. apiUrl должен указывать на API-эндпоинт платформы (например, pxl-*.altcraft.com), а не на трекинг-домен. Если SDK не может получить размещения (ошибка 404 No such route или Role Token processing error) — проверьте apiUrl.
• Истёкший токен. Токен должен быть подписан ключом, добавленным в ресурсе. Токен с истёкшей датой вернёт ошибку Role Token processing error.
• db_id в матчинге должен соответствовать ID базы данных, привязанной к токену. Иначе профиль не будет найден.
• HTTP-запросы. Для работы с API по незащищённому протоколу (dev-окружения) в манифесте приложения должен быть разрешён cleartext-трафик.