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

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 може залишитися для інших незалежних функцій застосунку.

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

Для картинок додайте окремий Notification Service Extension у Xcode та підключіть до нього продукт 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 не є URL Web badge. Оновлюйте пакет сторінки й скопійований service worker з того самого origin.

11 / Web / KMP

Підключення Kotlin Multiplatform

KMP використовує наші нативні Android, Apple та Web SDK без другої інсталяції. Окремий застосунок чи додаткові ключі PushPort не потрібні.

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 через SPM, створіть PushPortKMPBridge() у Swift та передайте callbacks APNs. Використайте createApplePushPort() з тими самими App ID та середовищем.

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 передавати не потрібно. Майстер-ключ діє на власні застосунки та застосунки команди після прийняття запрошення. Права ключа обмежені поточними правами співробітника: перегляд — читання, надсилання — створення push, керування — також зміна тегів. Враховуються права на окремі застосунки; видалення з команди чи зміна ролі одразу змінює доступ ключа. Ключ застосунку діє лише на один застосунок.

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 передавати не потрібно. Майстер-ключ діє на власні застосунки та застосунки команди після прийняття запрошення. Права ключа обмежені поточними правами співробітника: перегляд — читання, надсилання — створення push, керування — також зміна тегів. Враховуються права на окремі застосунки; видалення з команди чи зміна ролі одразу змінює доступ ключа. Ключ застосунку діє лише на один застосунок.

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 і ключа повертає 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 залишається після реєстрації й депозиту: додайте умови «Немає тегу» для виключення потрібних груп. Постбек лише змінює тег, не надсилає push і не визначає баєра автоматично. Невідомий тег сам по собі не виключає користувача з інших розсилок.

Завантажити 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, приблизний час та очікуваний результат.