Android SDK

Библиотека ru.pushdata:pushdata-android (Kotlin, подходит и для Java) регистрирует устройство по токену Firebase Cloud Messaging, обновляет его при смене, снимает при выходе и отмечает доставку, открытие и клик. Работает только с публичным ключом приложения (pk_…), который можно хранить в APK; отправки и контакты — с вашего сервера, секретным ключом.

Пакет публикуется. Пока ru.pushdata:pushdata-android не появился в Maven Central, подключите модуль android/sdk из репозитория PushData как локальный: include(':sdk') в settings.gradle.kts и implementation(project(":sdk")). API и шаги руководства те же.

Требования: Android 7.0+ (minSdk 24), проект Firebase, Google Play Services на устройстве.

1. Ключи приложения

В дашборде откройте Приложения → ваше приложение → Настройки: понадобятся ID приложения и публичный ключ pk_… (раздел «API-ключи»). Секретный ключ pd_… в приложение не попадает.

2. Firebase в PushData

1. В Firebase Console создайте проект и добавьте Android-приложение с вашим package name; скачайте google-services.json в модуль app/.
2. Project settings → Service accounts → Generate new private key — JSON сервисного аккаунта.
3. В дашборде откройте Приложения → ваше приложение → Провайдеры Push → FCM, укажите Project ID и загрузите JSON сервисного аккаунта.

3. Зависимости

// settings.gradle.kts / build.gradle.kts проекта: плагин google-services
plugins { id("com.google.gms.google-services") version "4.4.2" apply false }

// build.gradle.kts модуля app
plugins { id("com.google.gms.google-services") }

dependencies {
    implementation("ru.pushdata:pushdata-android:0.1.0")
    implementation(platform("com.google.firebase:firebase-bom:33.4.0"))
    implementation("com.google.firebase:firebase-messaging")
}

AndroidManifest.xml — сервис SDK (обновление токена, delivered, показ уведомления) и разрешение на уведомления:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

<application …>
    <service android:name="ru.pushdata.sdk.PushDataMessagingService" android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
</application>

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

Один раз на процесс — в Application.onCreate:

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        PushData.configure(
            context = this,
            appId = "APP_ID",        // Приложения → Настройки
            publicKey = "pk_…",      // Приложения → Настройки → API-ключи (публичный)
            // При включённой проверке идентичности — HMAC id пользователя с вашего сервера (шаг 8):
            // identityHashProvider = IdentityHashProvider { userId -> backend.identityHash(userId) },
        )
    }
}

5. Регистрация устройства

На Android 13+ сначала запросите POST_NOTIFICATIONS, затем — после входа пользователя — зарегистрируйте текущий токен. PushDataMessagingService.onNewToken повторит регистрацию при каждой смене токена с тем же userId.

lifecycleScope.launch {
    try {
        val registration = PushData.registerCurrentToken(userId = session.userId, tags = listOf("news"))
        Log.d("push", "device ${registration.id}, created=${registration.created}")
    } catch (e: PushDataException) {
        Log.w("push", "refused: ${e.status} ${e.code} — ${e.message}")
    }
}

Анонимное устройство — registerCurrentToken() без userId. Свой источник токена — PushData.registerDevice(token, userId, identityHash, tags, metadata).

6. Выход пользователя

lifecycleScope.launch { PushData.unregisterDevice() }   // DELETE /api/v1/public/devices

Один токен — одно устройство: повторная регистрация под другим userId переводит устройство новому пользователю.

7. События

В data каждого push PushData кладёт pushdata_notification_id и pushdata_device_id. Сервис отмечает delivered при получении и показывает уведомление (заголовок и текст из блока notification или из data title / body); тап открывает launcher-активити с data в extras. В onCreate и onNewIntent этой активити:

PushData.handleOpenedIntent(intent)   // отмечает opened, возвращает пару (notificationId, deviceId) или null

clicked — для явного действия внутри уведомления: PushData.track(PushEvent.CLICKED, notificationId, deviceId).

Своя обработка push (тихие сообщения, свой UI) — наследник сервиса с переопределённым onPushDataMessage(message): Boolean (верните true, чтобы не показывать стандартное уведомление); канал уведомлений pushdata_notifications и иконка — createNotificationChannel() / smallIcon().

8. Проверка идентичности

При включённой Приложения → Настройки → Проверка идентичности регистрация с userId должна нести заголовок X-Identity-Hash — hex HMAC-SHA256 от id пользователя на секрете идентичности приложения. Секрет не покидает ваш сервер: сделайте авторизованный эндпоинт, который возвращает хэш, и передайте IdentityHashProvider в configure (SDK спросит его перед каждой регистрацией) или identityHash в registerDevice. Без него PushData ответит 401 identity_unverified. Анонимным устройствам хэш не нужен.

9. Проверка

1. Запустите приложение на устройстве или эмуляторе с Google Play, разрешите уведомления.
2. Приложения → ваше приложение → Устройства: появилась строка с платформой Android и вашим user_id.
3. Отправить уведомление → цель «пользователь» или «устройство» → push приходит; в карточке уведомления растут delivered и opened.

Ошибки SDK — PushDataException(status, code, message) с кодом сервиса (unauthorized, identity_unverified, validation_error, not_found, rate_limited).