Документация

01 / Подключить приложение

Создание приложения

Войдите через Google или подтверждённую почту и пароль. Откройте «Приложения», создайте приложение и выберите Android. Настройки iOS и Web можно сохранить на будущее.

Скопируйте App ID из настроек приложения. Это идентификатор PushPort, а не ID проекта Firebase и не имя Android-пакета.

Перед началом

• Android-приложение с API 23 или выше.
• Тестовое устройство с Google Play Services и доступом в сеть.
• Доступ к Firebase-проекту этого приложения.

02 / Подключить приложение

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

Откройте нужный проект в консоли Firebase. В Project settings → Service accounts создайте приватный JSON-ключ. Загрузите его в настройки Android соответствующего приложения PushPort.

Приватный ключ хранится на сервере — не добавляйте его в Android-проект. Для этой интеграции PushPort приложению не нужны google-services.json и плагин Google Services. Собственная независимая интеграция Firebase может остаться.

• Используйте реквизиты правильного Firebase-проекта.
• Если задано ограничение пакета, оно должно совпадать с Android applicationId.
• Firebase Analytics для данных о локали не требуется.

03 / Подключить приложение

Установка Android SDK

SDK 0.3.0 пока распространяется как сборка Maven-репозитория, а не через Maven Central. Запросите сборку у поддержки и укажите путь к репозиторию в Gradle. Один AAR без метаданных не подключает транзитивные зависимости.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("/path/to/pushport-maven-repository")
            content { includeGroup("dev.pushport") }
        }
    }
}

dependencies {
    implementation("dev.pushport:android-sdk:0.3.0")
}

Инициализируйте SDK в классе Application и зарегистрируйте этот класс в AndroidManifest.xml. Если Application уже есть, добавьте вызов в него. Для приложений с несколькими процессами выполняйте инициализацию только в основном.

import android.app.Application
import dev.pushport.sdk.PushPort

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        PushPort.initWithContext(this, "PUSHPORT_APP_ID")
    }
}

<application android:name=".MyApplication" />

PushPort.requestNotificationPermission(this)

• Запросите разрешение на уведомления из видимой Activity, объяснив пользователю пользу.
• Firebase Messaging, WorkManager и компоненты манифеста подключаются с зависимостью.
• Запустите приложение, разрешите уведомления и найдите установку в «Аудитории».

04 / Работать с сообщениями

Работа с аудиторией

В аудитории показаны установки. Один человек с двумя устройствами может присутствовать дважды. Фильтруйте по языку, локали, примерной стране и состоянию подписки; полезные сочетания сохраняйте как сегменты.

SDK синхронизирует локаль приложения и системные локали, часовой пояс, версию и состояние уведомлений. Локаль de-DE отличается от языка de. Страна определяется приблизительно по IP и может быть неизвестна.

PushPort.setLocale(context, "de-DE")
PushPort.setLocale(context, null)
PushPort.setSubscribed(context, false)
PushPort.setSubscribed(context, true)
PushPort.sync(context)

• SUBSCRIBED — доступна отправка при наличии токена и разрешения.
• UNSUBSCRIBED / PERMISSION_DENIED — уведомления отключены приложением или системой.
• AWAITING_TOKEN / INVALID_TOKEN — нет пригодного для отправки токена.

05 / Работать с сообщениями

Отправка и расписание

Откройте «Кампании» выбранного приложения. Сохраните черновик с заголовком, текстом и аудиторией. Проверьте число доступных получателей и отправьте тест на свою установку.

Выберите отправку сейчас или будущую дату. Время показано в часовом поясе браузера и сохраняется как UTC. Расписание выполняется на сервере, даже если закрыть страницу.

• Приоритет перевода: точная локаль → язык → основной текст.
• Доступны разовые расписания. Повторы и отправка по местному времени каждого получателя пока не реализованы.
• Отмена останавливает ожидающие сообщения, но не отзывает уже переданные FCM.

06 / Работать с сообщениями

Изображения и ссылки

Укажите общедоступную HTTPS-ссылку на изображение и при необходимости HTTPS-ссылку перехода. В SDK 0.3.0 сначала появляется текст уведомления, затем картинка, если она успешно загрузилась.

Поддерживаются PNG, JPEG и WebP до 1 МиБ: каждая сторона не более 4096 пикселей, общий размер — не более 8 миллионов пикселей. Ссылки с авторизацией и адреса частных сетей не подходят.

• Изображение должно оставаться доступным во время отправки.
• Проверьте картинку и переход на реальном устройстве.
• Если картинка не загрузилась, текст уведомления всё равно может отобразиться.

07 / Проверить и разобраться

Результаты отправки

Принятие FCM означает, что провайдер принял запрос. Это не подтверждает показ на устройстве. Открытия учитываются отдельно, когда SDK сообщает о нажатии.

Смотрите результат кампании вместе с состоянием установки. Недействительный токен и временная ошибка провайдера — разные причины. Неопределённый результат не повторяется автоматически, чтобы не создать дубликат.

• Перед повтором проверьте подписку и системное разрешение.
• Состав аудитории при предпросмотре и в момент отправки может отличаться.
• Для разбора проблемы сравните время и ID установки.

08 / Проверить и разобраться

Решение проблем

Если установки нет в списке, запустите приложение и проверьте App ID, доступ к серверу и инициализацию SDK. Если установка есть, но недоступна, проверьте разрешение, подписку и состояние токена.

Если сообщение принято, но не видно, проверьте сеть устройства, настройки уведомлений и выбранную установку. Если проблема только с картинкой, откройте её URL без авторизации и проверьте формат и размер.

• Нет письма с кодом: проверьте спам и адрес, подождите минуту перед новым запросом.
• Ошибка Firebase: проверьте, что реквизиты отправителя относятся к проекту нужного приложения.
• Не помогло? Напишите через «Контакты»: App ID, примерное время и ожидаемый результат.