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

01 / Начало работы

Выбор платформы

Одно приложение PushPort может объединять настройки Android, iOS и Web. App ID обозначает приложение в PushPort. Android applicationId и Apple Bundle ID обозначают нативные приложения. Для входа в кабинет PushPort клиенту не нужно создавать свой Google OAuth-клиент.

02 / Начало работы

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

Создайте приложение и выберите платформы. Укажите Android package name, Apple Bundle ID или точный HTTPS origin сайта. В настройках подключите Firebase, APNs или Web Push, затем следуйте инструкции для соответствующего SDK.

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

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

• Apple SDK 0.0.2 опубликован. В настройках приложения загрузите APNs-ключ .p8, укажите Team ID, Key ID и нужную среду Sandbox или Production. Сервер отправляет напрямую через APNs. Перед рассылкой проверьте реальное устройство.
• Web Push использует сервис уведомлений браузера и ключи VAPID. Создавать Firebase-проект не нужно. Подготовлены маршруты провайдеров Chrome/Edge, Firefox и Safari.

03 / Начало работы

Команда

Предоставьте сотрудникам доступ к приложениям вашей команды.

Просмотр — аудитория и отчёты. Отправка — также кампании и сегменты. Управление — также настройки и удаление. Создание приложений доступно при управлении всей командой.

Состав команды, права сотрудников и ключи API доступны только владельцу.

Пригласить сотрудника

Приглашение автоматически отправляется на почту. Ссылку также можно скопировать. Для принятия нужно войти или зарегистрироваться с указанным email. Приглашение действует 7 дней.

Команда ↗

04 / Android / Firebase

Настройка Firebase для Android

Для этого способа подключения PushPort нужны Firebase-проект и один JSON-ключ сервисного аккаунта. Добавлять Firebase-зависимости или файл конфигурации Google в Android-приложение только ради PushPort не требуется.

1. Выберите нужный проект

   Откройте Firebase Console и создайте проект либо выберите проект, от имени которого будут отправляться Android-пуши. Google Analytics можно не включать. Firestore, Realtime Database и Firebase Authentication для отправки не нужны.

2. Проверьте пакет Android

   Найдите applicationId в build.gradle.kts модуля app и укажите его в поле Android-пакета приложения PushPort. Отдельно регистрировать Android-приложение в Firebase и указывать SHA-отпечатки для этого подключения не требуется. Существующие настройки Firebase для других функций приложения можно сохранить.

3. Включите API

   В Google Cloud выберите тот же проект → APIs & Services → Library. Проверьте, что включены Firebase Cloud Messaging API (HTTP v1) и Firebase Management API. Первый нужен для отправки, второй — чтобы PushPort прочитал номер отправителя проекта.

4. Скачайте приватный JSON-ключ

   В Firebase: Project settings → Service accounts → Firebase Admin SDK → Generate new private key. В скачанном JSON указаны type: service_account, project_id, client_email и private_key. Выбор языка примера в Firebase не меняет сам ключ.

5. Загрузите ключ в PushPort

   В кабинете откройте нужное приложение → «Настройки» → Firebase. Выберите скачанный JSON и загрузите его. Проверьте, что Firebase отмечен как настроенный. Файл относится к настройкам Android именно этого приложения.

6. Подключите SDK и проверьте установку

   Выполните инструкцию Android SDK ниже. Инициализируйте его с App ID из PushPort, запустите приложение, разрешите уведомления и найдите установку в «Аудитории». Перед рассылкой отправьте тест на эту установку.

Не перепутайте файлы и идентификаторы

Если Firebase не подключается

Нет доступа / 403

Проверьте проект и активность ключа. В Google Cloud IAM сервисному аккаунту нужны Firebase Viewer (roles/firebase.viewer) для чтения проекта и Firebase Cloud Messaging API Admin (roles/firebasecloudmessaging.admin) для отправки. Проверьте оба API из инструкции выше.

Не подходит JSON

Нужен ключ сервисного аккаунта, а не google-services.json и не файл OAuth-клиента Google.

Нет установки или уведомления

Проверьте App ID, ограничение пакета, Google Play Services, сеть, системное разрешение и подписку SDK. Firebase Analytics не управляет сбором локали.

05 / Android / Firebase

Установка Android SDK

Android SDK 0.0.5 опубликован в Maven Central. Добавьте google() и mavenCentral() в репозитории Gradle, затем implementation("dev.pushport:android-sdk:0.0.5"). Gradle скачает SDK и транзитивные зависимости.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

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

Инициализируйте 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 и компоненты манифеста подключаются с зависимостью.
• Запустите приложение, разрешите уведомления и найдите установку в «Аудитории».

06 / Apple / APNs

Подготовка Apple APNs

Apple SDK PushPort использует APNs напрямую. Ради PushPort не нужно создавать iOS-приложение в Firebase, подключать Firebase Messaging или скачивать GoogleService-Info.plist. Firebase может остаться в iOS-приложении, если он отдельно нужен для других функций.

1. Участие в Apple Developer

   Для скачивания SDK аккаунт Apple не нужен. Для реального теста APNs нужны активное участие в Apple Developer Program, подписанное приложение и подходящий provisioning profile.

2. Создайте или проверьте Bundle ID

   В Apple Developer → Certificates, Identifiers & Profiles → Identifiers выберите или зарегистрируйте явный App ID, совпадающий с Bundle Identifier приложения в Xcode. Включите Push Notifications.

3. Подготовьте ключ APNs

   В разделе Keys создайте ключ с Apple Push Notification service и настройте доступные ограничения окружения и topic для нужного приложения. Скачайте файл .p8: Apple даёт скачать его один раз.

4. Сохраните четыре значения

   Понадобятся Team ID, Key ID, Bundle ID и файл .p8. Проверьте, какие окружения и приложения разрешены ключу: новый ключ не обязательно подходит сразу для development и production.

5. Включите capability в Xcode

   Выберите основной target → Signing & Capabilities → + Capability → Push Notifications. Команда разработчика и профиль подписи должны поддерживать этот entitlement.

6. Выберите правильное окружение

   Используйте .sandbox, если aps-environment подписанного приложения — development, и .production для production, TestFlight и App Store. Окружение приложения, адрес APNs на сервере и ограничения ключа должны совпадать. Затем подключите SDK по инструкции ниже.

07 / Apple / APNs

Подключение Apple SDK

Подключите публичный Swift-пакет на Mac в Xcode. Минимальная версия iOS — 15.0. Аккаунт CocoaPods, файл Firebase и ручная загрузка фреймворка не требуются.

1. Добавьте пакет

   Xcode → File → Add Package Dependencies → вставьте URL ниже → Exact Version → 0.0.2. Добавьте продукт PushPort в основной target приложения.

https://github.com/IamFromUA/PushPortLibraryApple.git

Инициализируйте в делегате приложения

Возьмите App ID из настроек приложения в PushPort. Пример SwiftUI ниже передаёт SDK оба callback APNs. В UIKit добавьте те же вызовы в существующий AppDelegate.

Используйте .sandbox, если aps-environment подписанного приложения — development, и .production для production, TestFlight и App Store. Окружение приложения, адрес APNs на сервере и ограничения ключа должны совпадать. Затем подключите SDK по инструкции ниже.

import SwiftUI

import UIKit

import OSLog

import PushPort



@main

@MainActor

struct MyApp: App {

    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate

    var body: some Scene {

        WindowGroup { NotificationSettings() }

    }

}



@MainActor

final class AppDelegate: NSObject, UIApplicationDelegate {

    private let logger = Logger(subsystem: "app.notifications", category: "PushPort")



    func application(_ application: UIApplication,

                     didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {

        do {

            try PushPort.shared.initialize(

                appId: "YOUR_PUSHPORT_APP_ID",

                environment: .sandbox

            )

        } catch {

            logger.error("PushPort initialization failed")

        }

        return true

    }



    func application(_ application: UIApplication,

                     didRegisterForRemoteNotificationsWithDeviceToken token: Data) {

        PushPort.shared.didRegisterForRemoteNotifications(deviceToken: token)

    }



    func application(_ application: UIApplication,

                     didFailToRegisterForRemoteNotificationsWithError error: Error) {

        PushPort.shared.didFailToRegisterForRemoteNotifications(error: error)

    }

}

Запросите разрешение на уведомления

Покажите системный запрос после объяснения пользы, например по кнопке. Инициализация сама диалог не открывает. После отказа пользователь меняет разрешение в Settings.

import SwiftUI

import PushPort



@MainActor

struct NotificationSettings: View {

    @State private var result = ""

    @State private var requesting = false



    var body: some View {

        VStack {

            Button("Enable notifications") {

                requesting = true

                Task { @MainActor in

                    defer { requesting = false }

                    do {

                        let granted = try await PushPort.shared.requestPermission()

                        result = granted ? "Notifications allowed" : "Check notification settings"

                    } catch {

                        result = "Unable to request permission"

                    }

                }

            }

            .disabled(requesting)

            Text(result)

        }

    }

}

Системное разрешение и подписка PushPort — разные настройки. setSubscribed(false) сохраняет отказ от подписки; true не отменяет запрет системы. SDK автоматически получает языки приложения и системы, а также часовой пояс. setLocale(nil) возвращает автоматический выбор локали. Уже отправленные APNs-уведомления могут дойти после отключения подписки.

// Call from your app's settings action.

@MainActor

func updateNotifications(subscribed: Bool, locale: String?) async throws {

    try await PushPort.shared.setSubscribed(subscribed)

    try await PushPort.shared.setLocale(locale)

}



// locale: "uk-UA" for an override, nil for automatic selection.

// Handle errors in the calling view and update its displayed state.

Профили, согласие и диагностика уведомлений

Текущий SDK поддерживает подтверждённые профили, теги со строковыми значениями, подтверждённый вход/выход по External ID, явно переданные email/телефон/координаты и события. Подтверждение личности выдаёт ваш доверенный бэк; ключ API аккаунта нельзя встраивать в приложение. При необходимости задайте требование согласия до инициализации. Согласие на данные и разрешение уведомлений — отдельные настройки.

Получение, результаты вызова API уведомлений, подготовка/ошибки изображений, нажатия, сессии и время на экране сохраняются в очереди и повторно отправляются с подтверждением событий. Возврат в течение 60 секунд после нажатия считается прямым; в течение часа после получения без нажатия — предполагаемым влиянием. Принятие провайдером, подготовка SDK и успешный вызов API не доказывают, что человек увидел уведомление.

08 / Apple / APNs

Картинки и обработка уведомлений iOS

Для картинок добавьте в Xcode отдельный Notification Service Extension и подключите к нему продукт PushPortNotificationService. В основном приложении остаётся продукт PushPort.

1. Используйте класс расширения

   Замените созданный Xcode класс подклассом из примера. В NSExtensionPrincipalClass оставьте $(PRODUCT_MODULE_NAME).NotificationService.

2. Подготовьте уведомление с картинкой

   Apple SDK 0.0.2 скачивает до 5 МиБ по умолчанию и учитывает настройку проекта 1–20 МиБ, но для iOS действует потолок вложения 10 МиБ. JPEG/PNG/GIF и конвертация WebP в PNG при поддержке платформы обрабатываются с ограничением декодирования, общим таймаутом 20 секунд и уменьшением до 2000 пикселей по стороне. Ошибка сохраняет текст. Иконка уведомления берётся из установленного приложения; Android-поля small_icon и large_icon её не заменяют.

3. Обработайте нажатие в приложении

   Через onNotificationOpened приходят ID сообщения и необязательная безопасная HTTPS-ссылка. Способ перехода выбирает приложение. Ошибка картинки или истечение времени расширения сохраняют исходный текст.

import PushPortNotificationService



final class NotificationService: PushPortNotificationService {}

Для фоновой диагностики получения и изображений включите одинаковую App Group в приложении и расширении и укажите одно значение PushPortAppGroup в обоих Info.plist. Через группу передаются только ограниченные файлы событий; учётные данные установки остаются в приложении. События отправятся при следующей синхронизации приложения. Для самих картинок App Group не требуется.

<key>PushPortAppGroup</key>
<string>group.com.example.app.pushport</string>

09 / Web / KMP

Настройка Web Push

Web Push использует сервис уведомлений браузера и ключи VAPID. Создавать Firebase-проект не нужно. Подготовлены маршруты провайдеров Chrome/Edge, Firefox и Safari.

1. Сохраните адрес сайта

   Создайте приложение или включите Web в существующем. Укажите точный HTTPS-origin без пути, например https://example.com. Поддомены считаются разными origin.

2. Включите Web Push

   Приложение → Настройки → Web Push → Включить Web Push. PushPort создаст постоянную пару ключей и сохранит закрытый ключ на сервере. SDK получает только открытый ключ. Не меняйте ключи, пока их используют подписки.

3. Разместите service worker

   Подключите SDK по инструкции ниже и скопируйте worker на свой сайт. URL должен отдавать JavaScript с того же origin, а не HTML-страницу при отсутствии файла.

4. Запросите разрешение по нажатию

   Инициализируйте SDK после загрузки страницы, а разрешение запрашивайте непосредственно по нажатию кнопки. На iPhone/iPad нужен поддерживаемый сайт, добавленный на экран «Домой». После отказа разрешение меняют в настройках браузера.

10 / Web / KMP

Подключение Web SDK

Версия 0.0.2 подключается обычной npm-зависимостью из GitHub-релиза. Публикация в реестре npm ожидает настройки аккаунта издателя. При сборке сайта копируйте node_modules/@pushport/web-sdk/dist/pushport-sw.js в public/pushport-sw.js.

npm install https://github.com/IamFromUA/PushPortLibraryWeb/releases/download/0.0.2/pushport-web-sdk-0.0.2.tgz

import { PushPort } from '@pushport/web-sdk';



if (PushPort.isSupported()) {

  const push = await PushPort.initialize({

    appId: 'YOUR_PUSHPORT_APP_ID',

    serviceWorkerUrl: '/pushport-sw.js',

  });

  document.querySelector('#enable-push')?.addEventListener('click', () => {

    void push.requestPermission().catch(error => {

      const status = document.querySelector('#push-status');

      if (status) status.textContent = error.message;

    });

  });

}

Уже есть service worker? Подключите скопированный PushPort worker внутри существующего и передайте serviceWorkerRegistration при инициализации. Область действия и обновления контролирует сайт. SDK не заменяет чужой worker. HTTPS-ссылки из уведомлений открываются в пределах origin вашего сайта.

setSubscribed(false) отключает подписку и синхронизирует выбор. setLocale(null) возвращает автоматическое определение локали. После смены разрешений, языка или сети проверяйте status().lastSyncedAt и syncError.

Профили, согласие и диагностика уведомлений

Текущий SDK поддерживает подтверждённые профили, теги со строковыми значениями, подтверждённый вход/выход по External ID, явно переданные email/телефон/координаты и события. Подтверждение личности выдаёт ваш доверенный бэк; ключ API аккаунта нельзя встраивать в приложение. При необходимости задайте требование согласия до инициализации. Согласие на данные и разрешение уведомлений — отдельные настройки.

Получение, результаты вызова API уведомлений, подготовка/ошибки изображений, нажатия, сессии и время на экране сохраняются в очереди и повторно отправляются с подтверждением событий. Возврат в течение 60 секунд после нажатия считается прямым; в течение часа после получения без нажатия — предполагаемым влиянием. Принятие провайдером, подготовка SDK и успешный вызов API не доказывают, что человек увидел уведомление.

Web SDK 0.0.2 независимо скачивает большую картинку и HTTPS-иконку large_icon. Лимит по умолчанию 5 МиБ, в настройках проекта — 1–20 МиБ. При доступности декодирования/canvas браузера картинка уменьшается до 2000 пикселей, иконка — до 256. Внешний сервер изображений должен разрешать CORS. Показ зависит от браузера и ОС; имя Android-ресурса small_icon не является ссылкой Web badge. Обновляйте и пакет страницы, и скопированный service worker с того же origin.

11 / Web / KMP

Подключение Kotlin Multiplatform

KMP использует наши нативные SDK для Android, Apple и Web. Вторая установка не создаётся. Отдельное приложение или дополнительные ключи в PushPort для KMP не нужны.

commonMain.dependencies {

    implementation("dev.pushport:kmp-sdk:0.0.2")

}

1. Общий модуль

   Добавьте dev.pushport:kmp-sdk:0.0.2 в commonMain. Android SDK придёт транзитивно. Создайте один клиент на приложение и вызывайте его из UI/main-потока.

2. Android-приложение

   Создайте клиент через createAndroidPushPort(applicationContext), передав функцию получения текущей активной Activity. Не удерживайте уничтоженную Activity.

3. Apple-приложение

   Добавьте PushPort 0.0.2 через Swift Package Manager, создайте PushPortKMPBridge() в Swift и передайте callbacks APNs. В общем клиенте используйте createApplePushPort(). App ID и среда APNs должны совпадать.

4. Web-приложение

   Установите Web SDK в проект сайта, разместите worker на том же origin и передайте импортированный модуль в createWebPushPort. Kotlin/Wasm и нативные уведомления десктопа не входят в эту версию.

import dev.pushport.kmp.PushPort

import dev.pushport.kmp.PushPortConfiguration

import dev.pushport.kmp.AppleEnvironment



suspend fun initializePush(client: PushPort) {

    client.initialize(PushPortConfiguration(

        appId = "YOUR_PUSHPORT_APP_ID",

        appleEnvironment = AppleEnvironment.SANDBOX,

    ))

    client.setLocale(null)

}

Сборка проверена на macOS: отдельный Kotlin framework успешно связан со Swift-приложением и опубликованным Apple SDK. Реальная доставка на устройства и в браузеры проверяется отдельно.

Профили, согласие и диагностика уведомлений

Текущий SDK поддерживает подтверждённые профили, теги со строковыми значениями, подтверждённый вход/выход по External ID, явно переданные email/телефон/координаты и события. Подтверждение личности выдаёт ваш доверенный бэк; ключ API аккаунта нельзя встраивать в приложение. При необходимости задайте требование согласия до инициализации. Согласие на данные и разрешение уведомлений — отдельные настройки.

Получение, результаты вызова API уведомлений, подготовка/ошибки изображений, нажатия, сессии и время на экране сохраняются в очереди и повторно отправляются с подтверждением событий. Возврат в течение 60 секунд после нажатия считается прямым; в течение часа после получения без нажатия — предполагаемым влиянием. Принятие провайдером, подготовка SDK и успешный вызов API не доказывают, что человек увидел уведомление.

12 / Аудитория и сообщения

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

Пользователи, установки и собираемые данные

Автоматически: UUID установки, отдельный ID пользователя PushPort, Android ID при наличии, FCM-токен, разрешение и состояние подписки, язык и локали, часовой пояс, пакет и версии приложения/ОС/SDK, производитель и модель, оператор связи, сессии и время на экране. Бэк сохраняет последний IP и приблизительную страну от доверенного прокси. Фоновая синхронизация не считается открытием приложения.

Каждая новая установка получает новый PushPort userId. Перезапуск и обновление сохраняют ID. Android ID связывает только историю: пользователи не объединяются, теги после переустановки не переносятся. Существующие userId сохраняются. Явный подтверждённый login может связывать аккаунт.

Теги, email, телефон в E.164, координаты и события приложение передаёт явно. PushPort не читает контакты, IMEI, рекламный ID или GPS автоматически. Email и телефон в профиле не включают отправку почты или SMS.

Ваш бэк после проверки своего пользователя запрашивает подтверждение на пять минут: POST /api/v1/apps/{appId}/identity-tokens с installationId и externalId, затем возвращает token приложению. Токен сессии владельца используется только на бэке. При ошибке или истечении подтверждения получите новое. Вызовы SDK ставят изменения в очередь; PushPort.user(context) возвращает последний подтверждённый сервером профиль, status().syncError — ошибку синхронизации.

Если требуется согласие, вызовите setConsentRequired до инициализации. Согласие на данные и разрешение Android на уведомления — разные настройки. Отзыв останавливает последующий сбор, синхронизацию и показ пушей PushPort, но не отзывает уже отправленные запросы и не удаляет историю на сервере.

PushPort.setConsentRequired(this, true) // before init

PushPort.initWithContext(this, appId)

// After your consent flow:

PushPort.setConsentGiven(this, true)

// After your backend verifies the account:

PushPort.login(context, externalId, identityToken)

PushPort.setTags(context, mapOf("plan" to "pro"))

val confirmedUser = PushPort.user(context)

PushPort.logout(context)

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

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 — нет пригодного для отправки токена.

13 / Аудитория и сообщения

Партнёрская интеграция и API

Откройте приложение → Настройки → Ключи API. Создайте ключ для сервера партнёра и сразу скопируйте его: повторно посмотреть ключ нельзя. Храните ключ на сервере партнёра; не размещайте его в приложении или публичной ссылке. Приложение определяется по userId, App ID передавать не нужно. Мастер-ключ действует на собственные приложения и приложения команды после принятия приглашения. Права ключа ограничены текущими правами сотрудника: просмотр — чтение, отправка — создание пушей, управление — также изменение тегов. Учитываются права на конкретные приложения; удаление из команды или изменение роли сразу меняет доступ ключа. Ключ приложения по-прежнему действует только на одно приложение.

API принимает исходный PushPort userId в формате UUID, без префиксов и суффиксов. Это не токен FCM и не Android ID. Название параметра и оформление ID в ссылке задаёт разработчик приложения. Партнёр удаляет оформление и возвращает исходный UUID в запросах.

Ссылка из приложения

После успешной синхронизации получите подтверждённый userId. Если профиль ещё не получен, дождитесь синхронизации и повторите. Приложение само формирует и открывает ссылку; используйте URL builder для кодирования значения. При переключении аккаунта дождитесь подтверждения нового профиля.

val userId = PushPort.user(context)?.userId
if (userId != null) {
    val offerUrl = android.net.Uri.parse("https://example.com/offer")
        .buildUpon()
        .appendQueryParameter("sub_id_10", userId + "::|00030")
        .build().toString()
    // Open offerUrl using your application flow.
} else {
    PushPort.sync(context) // async; retry after synchronization
}

Проверка установки

Проверка установки — только один ID. Ответ содержит installId, appId (Android package name), customAppName, locale (язык), countryCode (может быть null), timezone и type: api. Приложение определяется по userId, App ID передавать не нужно. Мастер-ключ действует на собственные приложения и приложения команды после принятия приглашения. Права ключа ограничены текущими правами сотрудника: просмотр — чтение, отправка — создание пушей, управление — также изменение тегов. Учитываются права на конкретные приложения; удаление из команды или изменение роли сразу меняет доступ ключа. Ключ приложения по-прежнему действует только на одно приложение.

POST /api/v1/partner/getInstall/

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json



{"id":"11111111-2222-4333-8444-555555555555"}

Отправка списку

Отправка принимает от 1 до 10 000 ID. Повторы удаляются; неизвестные и чужие ID возвращаются в excludedUserIds. Если не найден никто — 422. click_uuid может быть массивом; строка поддерживается для совместимости. Одна рассылка — один заголовок, текст и ссылка для всего списка. Общий API использует userIds, title, body, imageUrl и clickUrl. Если список содержит пользователей нескольких приложений, ответ содержит messages — отдельное задание с messageId для каждого приложения, общие requestedCount, queuedCount и excludedUserIds. Проверяйте статус каждого messageId. Для одного приложения формат ответа прежний.

POST /api/v1/partner/push/

Authorization: Bearer YOUR_API_KEY


Content-Type: application/json



{

  "header": "Hello",

  "content": "Your notification",

  "click_uuid": ["11111111-2222-4333-8444-555555555555", "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee"],

  "chrome_web_image": "https://cdn.example.com/image.jpg",
  "large_icon": "https://cdn.example.com/avatar.png",
  "small_icon": "ic_stat_offer",

  "url": "https://example.com/offer"

}

Статус отправки

Idempotency-Key необязателен. Без него каждый запрос создаёт новую отправку, включая повторы. Если заголовок передан, при повторе используйте тот же ключ. Изменение содержимого с тем же ключом — 409. Ответ 202 означает очередь, не доставку. При выполнении выбирается одна актуальная подписка Android на userId; отключённые пропускаются. Статус доступен тому же ключу по messageId. Уже принятые задачи продолжают работу после отзыва ключа.

60 запросов в минуту на ключ, тело отправки до 2 МиБ. scheduledAt — Unix-время в миллисекундах, не далее 366 дней. При 429 учитывайте Retry-After. accepted — принятие провайдером, opened — открытие, unknown — неопределённый результат без слепого повтора.

SDK PushPort Android 0.0.4+ поддерживает цветную миниатюру отдельно от большой картинки. В CSV/XLSX и партнёрском API это large_icon, в общем API — largeIcon. Укажите публичную HTTPS-ссылку или имя ресурса приложения. Рекомендуется квадратное изображение 256 × 256. Приложения с SDK OneSignal также поддерживают эти поля; старые версии PushPort игнорируют их и показывают прежнее уведомление.

small_icon (в общем API — smallIcon) — имя ресурса drawable/mipmap без расширения, например ic_stat_offer. Ресурс должен уже быть в APK: белый силуэт на прозрачном фоне. Ссылка или загрузка в галерею не подходит для иконки строки состояния.

GET /api/v1/public/notifications/MESSAGE_ID

Authorization: Bearer YOUR_API_KEY

Регистрация, покупка и теги пользователя

Передайте один и тот же PushPort userId в ссылке WebView и серверу партнёра. Когда партнёр получит подтверждение регистрации или покупки, его сервер обновляет теги через API. PushPort сам не определяет действия на стороннем сайте.

Теги разделены по приложениям. Даже если один человек использует несколько приложений, передавайте App ID нужного приложения и его PushPort userId. App ID доступен в «Обзор → App ID» и «Настройки → Ключи API», а также через GET /api/v1/public/app с ключом приложения. Для каждого приложения нужен свой ключ. При несовпадении App ID и ключа API возвращает 403. Старые адреса без App ID продолжают определять приложение по ключу.

Создайте ключ приложения с правом USER_TAGS_WRITE («Изменение тегов пользователей»). Существующие ключи автоматически не получают это право. PATCH изменяет только перечисленные теги: строка "true" устанавливает признак, null удаляет тег. Повтор одинакового запроса безопасен. GET по тому же пути требует INSTALLATIONS_READ. Неизвестный или чужой userId возвращает 404; профиль не создаётся.

PATCH /api/v1/public/apps/APP_ID/users/USER_ID/tags
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"tags":{"registration":"true"}}

// After a confirmed purchase:
// {"tags":{"purchase":"true"}}
// Remove a tag: {"tags":{"purchase":null}}

До 50 тегов у пользователя, имя до 64 символов, значение до 256. Имена и значения чувствительны к регистру, значения — строки, а не boolean. Если postback пришёл раньше регистрации устройства в PushPort, сохраните его у себя и повторите после синхронизации. Ключ API храните только на сервере.

В аудитории и редакторе рассылки отображаются реально полученные теги выбранного приложения. Нажмите тег, чтобы добавить условие «Есть тег»; выберите «Равно» и значение для точного совпадения. Все условия объединяются через И, максимум 10. «Не равно» включает отсутствие тега. Фильтр можно сохранить как сегмент. Системный тег install="true" добавляется автоматически независимо от разрешения пушей, в том числе существующим пользователям. Его нельзя удалить или изменить; он не входит в лимит 50 пользовательских тегов.

Чтобы отправить всем, кроме пользователей с определёнными тегами, выберите «Исключить пользователей с тегом» и укажите названия, например reg и dep. Пользователь с любым из них исключается независимо от значения. Пользователи без обоих тегов остаются в аудитории. До 10 условий объединяются через И; они работают и в авторассылках, и в сохранённых сегментах. «Не равно» — другое условие: оно сравнивает конкретное значение.

Запланированная рассылка выбирает аудиторию на момент запуска и повторно проверяет теги перед отправкой каждому получателю. Если пользователь вышел из сегмента, отправка пропускается с причиной audience_changed. Уже переданный провайдеру пуш отменить нельзя. Тег не запускает рассылку автоматически: создайте и отправьте либо запланируйте кампанию.

Партнёрские API-пуши

Откройте проект → Настройки проекта → Разное → Партнёрские API-пуши. Галочки независимы и по умолчанию выключены; после изменения сохраните настройки.

1. Отмечать пользователей после принятия API-пуша

   Ставит api_managed=true, когда новый пуш через партнёрский или общий API принят в очередь. Это не подтверждение доставки на устройство. Постбеки и тестовые пуши из админки тег не ставят.

2. Автоматически исключать отмеченных пользователей из рассылок

   Действует для ручных и авторассылок, включая ожидающих отправки получателей. API-пуши продолжают идти. Пользователи остаются видны в аудитории.

Если автоматическое исключение выключено, добавьте в аудитории ручной или авторассылки условие: тег api_managed, «Не равно», значение true. Пользователи без этого тега останутся в аудитории рассылки.

Тег относится к пользователю и его связанным устройствам внутри одного проекта. Пользователь остаётся в аудитории, статус подписки не меняется. Постбеки reg/dep, запрос данных об установке и тестовые пуши из админки этот тег не ставят. Обновление SDK не требуется. Импорт и изменения тегов со стороны приложения или партнёра не могут перезаписать системную метку.

Запланированный API-пуш ставит тег сразу после принятия нового запроса в очередь. Ошибочные и отклонённые запросы пользователей не отмечают. Автоматическое исключение перепроверяет ожидающих получателей; уже переданный провайдеру пуш отменить нельзя.

Пример: после установки общие пуши идут всем. Когда Extendy передаёт первый API-пуш пользователю, при включённой первой галочке ставится api_managed=true. Если включена и вторая галочка, общие рассылки для него прекращаются, партнёрские API-пуши продолжаются. Сам постбек reg или dep эту маршрутизацию не меняет.

Теги через постбек

Для одной ссылки на все приложения откройте API-ключи аккаунта и создайте мастер-ключ с правом «Изменение тегов пользователей». Выберите «Без срока», если нужен постоянный ключ. Передайте ключ в key, PushPort userId без суффикса — в user, событие — в tag. Приложение определяется по userId; App ID не нужен. Любые пользовательские теги, например reg, dep, reg_team1 и buyer_team1, принимаются без предварительного списка. Мастер-ключ работает только в приложениях, которыми аккаунт может управлять. Ключ приложения с тем же правом также подходит, но только для своего приложения. Старые ключи ppb_ сохраняют свои ограничения по тегам. user_id — допустимый вариант user; настоящий Android ID не подходит.

https://pushport.dev/postback?key=ACCOUNT_API_KEY&user=USER_ID&tag=dep

Для обычных рассылок используйте общие reg и dep. Для нескольких байеров или ветки Extendy добавьте отдельные теги, например buyer_team1 или buyer_extendy, и настройте аудиторию. install сохраняется после регистрации и депозита: добавьте условия «Нет тега» для исключения нужных групп. Постбек только обновляет тег, не отправляет пуш и не определяет байера автоматически. Неизвестный тег сам по себе не исключает пользователя из других рассылок.

Скачать OpenAPI JSON ↓

14 / Аудитория и сообщения

Авторассылки

XLSX до 32 МБ; CSV до 1 МБ. Встроенные PNG/JPEG/GIF в image_url и large_icon автоматически сохраняются в галерею после проверки. Картинки в small_icon переносятся в large_icon. Из Google Таблиц скачайте XLSX: CSV не содержит картинок. Повторные изображения используются заново.

После проверки картинки сохранятся в папку с именем файла или в выбранную вами папку.

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

XLSX до 32 МБ или CSV UTF-8 до 1 МБ, 5 000 сообщений и 200 языков. Эмодзи поддерживаются. Порядок или случайный выбор задаётся в настройках.

Колонки: title, message, language, image_url, url. Обязательны title и message; язык задаётся в строке или выше. Необязательные иконки Android: large_icon, small_icon (SDK PushPort 0.0.4+ или OneSignal).

Поддерживаемые форматы

Один язык: title, message. Язык задаётся в поле ниже.

Несколько языков: title, message, language. Язык указывается в каждой строке.

С картинками и ссылками: title, message, language, image_url, url. Картинки и ссылки необязательны.

Если код языка не поддерживается, можно подтвердить исключение всех строк с этим кодом. Замена кода не предлагается. Исходный файл не изменяется.

title,message,language,image_url,url,large_icon,small_icon
🎁 Hello!,Your message,en,,,https://example.com/avatar.png,ic_stat_offer

1. Загрузить таблицу

   Проверить файл

2. Приложения

   Проверить аудиторию

3. Время отправки, через запятую

   Часовой пояс · UTC · 15:00, 18:00, 21:00

4. Часовое время отправки

   В местном режиме 15:00 означает 15:00 на устройстве пользователя. При неизвестном часовом поясе используется резервный. Переходы на летнее время учитываются.

5. Период

   Даты включительно. В местном режиме период действует в часовом поясе каждого пользователя. Пустая дата означает отсутствие ограничения.

6. Выбор сообщений

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

7. Сохранить без запуска

   Сохранено без запуска

8. Запустить

   Повторять после последнего сообщения

После простоя прошедший слот отмечается пропущенным, очередь сдвигается на одно сообщение и продолжается в ближайший будущий слот.

Откройте авторассылку и нажмите «Редактировать авторассылку». Активную сначала поставьте на паузу. Можно изменить название, сообщения, картинки, расписание, период, аудиторию и повтор. После сохранения рассылка остаётся на паузе: проверьте аудиторию и нажмите «Продолжить». Завершённую или окончательно остановленную рассылку редактировать нельзя.

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

Чтобы отправить всем, кроме пользователей с определёнными тегами, выберите «Исключить пользователей с тегом» и укажите названия, например reg и dep. Пользователь с любым из них исключается независимо от значения. Пользователи без обоих тегов остаются в аудитории. До 10 условий объединяются через И; они работают и в авторассылках, и в сохранённых сегментах. «Не равно» — другое условие: оно сравнивает конкретное значение.

Откройте «Отправки → Библиотека» или библиотеку в меню аккаунта. Создайте шаблон рассылки или авторассылки прямо в библиотеке. Сообщения авторассылки можно добавить вручную, таблица не обязательна. Сохранённый шаблон редактируется с его карточки. Также можно сохранить шаблон из существующей рассылки. Проект выбирается при использовании шаблона: проверьте настройки и сохраните черновик или авторассылку на паузе перед запуском. Библиотека личная; редактирование и удаление не меняют готовые копии.

История отправок

15 / Аудитория и сообщения

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

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

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

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

Библиотека шаблонов

Откройте «Отправки → Библиотека» или библиотеку в меню аккаунта. Создайте шаблон рассылки или авторассылки прямо в библиотеке. Сообщения авторассылки можно добавить вручную, таблица не обязательна. Сохранённый шаблон редактируется с его карточки. Также можно сохранить шаблон из существующей рассылки. Проект выбирается при использовании шаблона: проверьте настройки и сохраните черновик или авторассылку на паузе перед запуском. Библиотека личная; редактирование и удаление не меняют готовые копии.

Копируются текст, переводы, ссылки на изображения, условия аудитории и настройки авторассылки. ID устройств, даты и прогресс не переносятся. Ссылки на изображения остаются общими: сохраняйте исходные файлы доступными.

16 / Аудитория и сообщения

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

Откройте «Галерею» проекта и выберите несколько PNG/JPEG/GIF сразу. Каждый успешно загруженный файл получает свою HTTPS-ссылку; неудачные загрузки можно повторить отдельно. Выбирайте изображения из галереи в обычных и автоматических рассылках — для большой картинки или миниатюры Android. Можно также вставить внешнюю публичную HTTPS-ссылку. Разделы «Большие изображения» и «Иконки» разделяют файлы по назначению. Выберите раздел перед загрузкой. Право управления позволяет перенести файл между разделами без изменения ссылки и существующих сообщений. В редакторе галерея учитывает выбор большой картинки или миниатюры Android. «Все изображения» позволяет использовать любой файл. Иконки строки состояния остаются в ресурсах приложения.

PNG, JPEG или GIF, до 5 МБ на файл. Изображения уменьшаются до 2000 px по стороне без обрезки; для GIF используется первый кадр. До 100 изображений / 500 МБ на проект. Файлы доступны по публичной ссылке. Отдельный лимит скачивания в Android SDK 0.0.3+ — 5 МиБ по умолчанию, настраивается от 1 до 20 МиБ в настройках проекта. Android SDK 0.0.2 и более ранние версии сохраняют лимит 1 МиБ. Apple и Web SDK 0.0.2 также используют 5 МиБ по умолчанию и настройку проекта; потолок вложений iOS — 10 МиБ. CORS для Web и расширение/App Group Apple описаны в инструкциях платформ.

• Право отправки позволяет загружать; право управления — удалять.
• Удаление картинки делает её ссылку недоступной в существующих и запланированных сообщениях. При удалении проекта удаляются все его изображения. Уже загруженные на устройства копии остаются.
• Проверьте предпросмотр и отправьте тест на устройство.

Для большой картинки используйте пропорции 2:1, например 1024 × 512. SDK принимает до 4096 пикселей по стороне и 8 миллионов пикселей суммарно, при загрузке в галерею картинка уменьшается до 2000 пикселей по стороне. SDK 0.0.4 и более ранние версии уменьшают внешние картинки до 1024; SDK 0.0.5+ сохраняет до 2000 и поддерживает GIF без анимации. Иконка строки состояния — 24 dp: растровые варианты 24, 36, 48, 72 и 96 пикселей для mdpi–xxxhdpi; также подходит векторный ресурс 24 dp.

Иконки Android-уведомления

SDK PushPort Android 0.0.4+ поддерживает цветную миниатюру отдельно от большой картинки. В CSV/XLSX и партнёрском API это large_icon, в общем API — largeIcon. Укажите публичную HTTPS-ссылку или имя ресурса приложения. Рекомендуется квадратное изображение 256 × 256. Приложения с SDK OneSignal также поддерживают эти поля; старые версии PushPort игнорируют их и показывают прежнее уведомление.

small_icon (в общем API — smallIcon) — имя ресурса drawable/mipmap без расширения, например ic_stat_offer. Ресурс должен уже быть в APK: белый силуэт на прозрачном фоне. Ссылка или загрузка в галерею не подходит для иконки строки состояния.

Стандартные ресурсы PushPort: ic_stat_pushport_default и ic_pushport_large_icon_default. Если ресурс отсутствует или загрузка не удалась, остаются текст и стандартные иконки. Дополнительные вызовы SDK и разрешения не нужны. При удалении неиспользуемых ресурсов в release-сборке сохраните динамически выбранные ресурсы в res/raw/keep.xml:

<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/ic_stat_offer,@drawable/ic_stat_pushport_default,@drawable/ic_pushport_large_icon_default" />

17 / Аудитория и сообщения

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

Успешная отправка означает, что запрос принят FCM, APNs или push-службой браузера. Это не подтверждение показа на устройстве. Зарегистрированные открытия, ошибки и неопределённые результаты учитываются отдельно.

Android SDK 0.0.3+ добавляет «Отчеты о доставке» в каждом приложении: получение SDK, создание уведомления Android, загрузку и добавление картинки с размером, временем и HTTP-кодом, нажатия, ошибки открытия ссылки и синхронизации. Фильтруйте по дате или ID пользователя/установки/сообщения, смотрите хронологию. Принятие FCM не подтверждает доставку; создание Android не доказывает, что пользователь увидел пуш, а открытие ссылки — загрузку сайта. Старые SDK работают, но не передают эти события. Регистрации, депозиты и редепозиты по-прежнему сообщает партнер.

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

18 / Аудитория и сообщения

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

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

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

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