Быстрый старт

В статье приведен пример быстрой интеграции Altcraft mSDK с Firebase Cloud Messaging (FCM). После выполнения указанных шагов ваше приложение сможет получать push-уведомления Altcraft.

Для использования Huawei Mobile Services или RuStore необходимо добавить соответствующие SDK в проект и реализовать их интерфейсы, используя тот же подход, что показан для Firebase.

Шаг 0. Предварительные условия

SDK push-провайдеров интегрированы в проект приложения (см. инструкции по интеграции push провайдеров);
В приложение добавлен класс, расширяющий Application();
Все необходимые сущности (ресурс, рассылка, шаблон, база профилей) заранее созданы в платформе Altcraft;
Для отправки push-уведомлений на устройствах с Android 13 (Tiramisu) требуется явное разрешение пользователя;
Подготовьте backend вашего приложения к работе с JWT.

Шаг 1. Подключение Altcraft mSDK к приложению

mSDK разбит на модули. Модуль активизируется добавлением его зависимости — отдельная регистрация не требуется: каждый модуль регистрируется автоматически при запуске приложения.

Для push-сценария необходимы два модуля:

android-sdk-core — базовый модуль (инициализация, аутентификация, ретраи);
android-sdk-push — push-уведомления.

Добавьте зависимости в файл build.gradle.kts уровня приложения (app level):

    dependencies {
        implementation("com.altcraft:android-sdk-core:X.Y.Z")
        implementation("com.altcraft:android-sdk-push:X.Y.Z")
    }

Выполните синхронизацию изменений Gradle.

Шаг 2. Реализация JWTInterface

Выполните реализацию интерфейса SDK, предназначенного для предоставления JWT-токена.

В модуле приложения создайте класс, реализующий JWTInterface, и переопределите getJWT():

import com.altcraft.sdk.platform.authenticate.external.jwt.JWTInterface

class JWTProvider(private val context: Context /** добавьте свойство context если это необходимо*/) : JWTInterface {
    override fun getJWT(): String?{
      // ваш код, возвращающий актуальный JWT-токен
    }
}

Обратите внимание

getJWT() — синхронная функция. Поток выполнения SDK будет приостановлен до получения JWT;
Рекомендуется, чтобы getJWT() возвращал значение немедленно из кэша (in-memory, SharedPreferences или EncryptedSharedPreferences). Это ускорит выполнение запросов;
Желательно подготовить актуальный JWT как можно раньше, например, на старте приложения, и сохранить его в кэш, чтобы при обращении SDK токен был доступен без задержек. При отсутствии значения допустимо вернуть null.

Пример реализации с использованием suspend-функции получения токена

import android.content.Context
import com.altcraft.sdk.platform.authenticate.external.jwt.JWTInterface
import kotlinx.coroutines.runBlocking

class JWTProvider(private val context: Context /** добавьте свойство context если это необходимо*/) : JWTInterface {
    private suspend fun fetchJwt(context: Context): String? {
        // ваш код, возвращающий актуальный JWT-токен
        return jwt
    }

    override fun getJWT(): String? = runBlocking {
        fetchJwt(context)
    }
}

Шаг 3. Регистрация провайдера JWT

Зарегистрируйте провайдера JWT в Application.onCreate():

import android.app.Application
import com.altcraft.sdk.AltcraftSDK

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.auth.setJWTProvider(JWTProvider(/** добавьте свойство context если это необходимо*/))
    }
}

Шаг 4. Реализация интерфейса FCM

В модуле приложения создайте класс, реализующий FCMInterface:

Пример реализации

import com.altcraft.sdk.push.platform.token.provider.FCMInterface
import com.google.firebase.Firebase
import com.google.firebase.messaging.FirebaseMessaging
import com.google.firebase.messaging.messaging
import kotlinx.coroutines.tasks.await

/**
 * FCM implementation for managing Firebase Cloud Messaging tokens.
 *
 * Provides methods to retrieve and delete FCM tokens via the Firebase SDK.
 */
class FCMProvider : FCMInterface {

    /**
     * Retrieves the current FCM token.
     *
     * Returns `null` if an error occurs during retrieval.
     *
     * @return The FCM token or `null` on failure.
     */
    override suspend fun getToken(): String? {
        return try {
            Firebase.messaging.token.await()
        } catch (e: Exception) {
            null
        }
    }

    /**
     * Deletes the current FCM token.
     *
     * Invokes [completion] with `true` if successful, `false` otherwise.
     *
     * @param completion Callback with the result of the deletion.
     */
    override fun deleteToken(completion: (Boolean) -> Unit) {
        try {
            FirebaseMessaging.getInstance().deleteToken().addOnCompleteListener {
                completion(it.isSuccessful)
            }
        } catch (e: Exception) {
            completion(false)
        }
    }
}

Шаг 5. Создание сервиса, расширяющего `FirebaseMessagingService()`

В модуле приложения создайте класс, расширяющий FirebaseMessagingService, и реализуйте в нём метод onMessageReceived() с вызовом AltcraftSDK.push.receiver.takePush() для передачи данных push-уведомления в SDK:

Пример создания сервиса

import com.altcraft.sdk.AltcraftSDK
import com.altcraft.sdk.push.push
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

/**
 * FCM service for handling push tokens and messages.
 */
class FCMService : FirebaseMessagingService() {

    /**
     * Called when a new FCM token is generated.
     *
     * @param token The new FCM token.
     */
    override fun onNewToken(token: String) {
        super.onNewToken(token)
    }

    /**
     * Called when a push message is received.
     *
     * Forwards the message to all receivers with additional metadata.
     *
     * @param message The received [RemoteMessage].
     */
    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)

        if (AltcraftSDK.push.receiver.isAltcraftPush(message.data)) {
            AltcraftSDK.push.receiver.takePush(this@FCMService, message.data)
        }
    }
}

Шаг 6. Регистрация сервиса FCM в манифесте приложения

Зарегистрируйте сервис Firebase Cloud Messaging в AndroidManifest.xml приложения:

<!-- FCM service -->
<service
    android:name="<your_package_name>.FCMService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Шаг 7. Регистрация провайдера FCM в `Application.onCreate()`

Зарегистрируйте провайдера Firebase Cloud Messaging в Application.onCreate():

import android.app.Application
import <your_package_name>.FCMProvider
import com.altcraft.sdk.AltcraftSDK
import com.altcraft.sdk.push.push

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.push.token.setFCMTokenProvider(FCMProvider())
    }
}

Шаг 7.5. Запрос разрешения на уведомления

На устройствах с Android 13+ перед подпиской необходимо запросить у пользователя разрешение на отправку уведомлений. Используйте AltcraftSDK.push.requestNotificationPermission():

AltcraftSDK.push.requestNotificationPermission(context = this, activity = this)

Шаг 8. Инициализация SDK

В Application.onCreate() создайте переменную конфигурации и выполните инициализацию с помощью функции initialization().

Обратите внимание — функция initialization() должна выполняться после регистрации всех используемых провайдеров (и JWT-провайдера, и провайдеров push-токенов).

Подробнее об инициализации

AltcraftSDK
 // Инициализация SDK и установка конфигурации
   └── fun initialization(context: Context, configuration: AltcraftConfiguration, complete: ((Result<Unit>) -> Unit)? = null): Unit

fun initialization(context: Context, configuration: AltcraftConfiguration, complete: ((Result<Unit>) -> Unit)? = null): Unit

Параметры конфигурации AltcraftConfiguration.Builder:

Параметр	Тип	Описание
`apiUrl`	`String`	URL вашего Altcraft-инстанса
`rToken`	`String? = null`	Роль-токен (rToken), если SDK работает через rToken
`appInfo`	`AppInfo? = null`	Данные о приложении: `appID`, `appIID`, `appVer`
`enableLogging`	`Boolean? = null`	Включение внутреннего логирования SDK

Конфигурация push-модула добавляется вызовом pushConfig():

Параметр `PushConfiguration`	Тип	Описание
`icon`	`Int?`	Ресурс иконки для push-уведомлений
`providerPriority`	`List<String>`	Порядок push-провайдеров по приоритету
`pushReceiverModules`	`List<String>`	Префиксы пакетов, в которых находятся реализации `PushReceiver`
`pushChannelName`	`String?`	Имя канала push-уведомлений
`pushChannelDescription`	`String?`	Описание канала push-уведомлений

Пример инициализации:

import android.app.Application
import <your_package_name>.FCMProvider
import com.altcraft.sdk.AltcraftSDK
import com.altcraft.sdk.config.AltcraftConfiguration
import com.altcraft.sdk.push.config.PushConfiguration
import com.altcraft.sdk.push.config.pushConfig
import com.altcraft.sdk.push.push

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        AltcraftSDK.auth.setJWTProvider(JWTProvider(applicationContext))
        AltcraftSDK.push.token.setFCMTokenProvider(FCMProvider())

        val config = AltcraftConfiguration.Builder(
            apiUrl = "https://pxl-your-instance.altcraft.com",
            enableLogging = true
        )
            .pushConfig(
                PushConfiguration(
                    icon = R.drawable.your_icon
                )
            )
            .build()

        AltcraftSDK.initialization(context = this, configuration = config)
    }
}

Шаг 9. Выполнение подписки на push-уведомления

С помощью функции subscribe() выполните подписку на push-уведомления в любом удобном для вас месте кода, например, после предоставления разрешения на отправку уведомлений:

AltcraftSDK
└──  val push: Push
    └── val subscription: SubscriptionAPI
        // Подписка на push-уведомления (status = SUBSCRIBED)
        ├─ fun subscribe(
              context: Context,
              sync: Boolean = true,
              profileFields: Map<String, Any?>? = null,
              customFields: Map<String, Any?>? = null,
              cats: List<CategoryData>? = null,
              replace: Boolean? = null,
              skipTriggers: Boolean? = null
            ): Unit

Пример выполнения подписки:

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        AltcraftSDK.push.requestNotificationPermission(context = this, activity = this)

        NotificationPermissionHandler.isGranted(
            activity = this,
            onGranted = {
                if(isUnsubscribed()){
                    AltcraftSDK.push.subscription.subscribe(context = this)
                }
            }
        )
    }
}

Шаг 0. Предварительные условия​

Шаг 1. Подключение Altcraft mSDK к приложению​

Шаг 2. Реализация JWTInterface​

Шаг 3. Регистрация провайдера JWT​

Шаг 4. Реализация интерфейса FCM​

Шаг 5. Создание сервиса, расширяющего FirebaseMessagingService()​

Шаг 6. Регистрация сервиса FCM в манифесте приложения​

Шаг 7. Регистрация провайдера FCM в Application.onCreate()​

Шаг 7.5. Запрос разрешения на уведомления​

Шаг 8. Инициализация SDK​

Шаг 9. Выполнение подписки на push-уведомления​