Documentation

01 / Bien démarrer

Choisir une plateforme

Une application PushPort peut réunir les paramètres Android, iOS et Web. L’App ID l’identifie dans PushPort. L’applicationId Android et le Bundle ID Apple identifient les applications natives. La connexion au tableau de bord PushPort ne nécessite pas votre propre client Google OAuth.

02 / Bien démarrer

Créer une application

Créez une application et choisissez ses plateformes. Enregistrez le package Android, le Bundle ID Apple ou l’origine HTTPS exacte du site. Configurez Firebase, APNs ou Web Push dans les paramètres, puis suivez le guide du SDK correspondant.

Copiez l’App ID dans les paramètres. C’est un identifiant PushPort, pas l’ID du projet Firebase ni le nom du package Android.

Avant de commencer

• Le SDK Apple 0.0.2 est publié. Dans les réglages de l’application, importez la clé APNs .p8 avec Team ID, Key ID et l’environnement Sandbox ou Production. Le serveur envoie directement par APNs. Vérifiez un appareil réel avant une campagne.
• Web Push utilise le service push du navigateur et les clés VAPID. Aucun projet Firebase n’est nécessaire. Les routes des fournisseurs Chrome/Edge, Firefox et Safari sont préparées.

03 / Bien démarrer

Équipe

Donnez à vos collaborateurs accès aux applications de votre équipe.

Lecture : audience et rapports. Envoi : aussi campagnes et segments. Gestion : aussi réglages et suppression. La création d’applications nécessite la gestion de toute l’équipe.

Seul le propriétaire gère les membres, les droits et les clés API.

Inviter un collaborateur

L’invitation est envoyée automatiquement par email. Vous pouvez aussi copier le lien. Pour accepter, connectez-vous ou inscrivez-vous avec l’adresse invitée. Validité : 7 jours.

Équipe ↗

04 / Android / Firebase

Configurer Firebase pour Android

Cette intégration PushPort nécessite un projet Firebase et une clé JSON de compte de service. Aucun fichier de configuration Google ni dépendance Firebase à ajouter manuellement dans l’application Android pour PushPort.

1. Choisir le bon projet

   Dans Firebase Console, créez ou sélectionnez le projet qui enverra les notifications Android. Google Analytics peut rester désactivé. Firestore, Realtime Database et Firebase Authentication ne sont pas nécessaires à l’envoi.

2. Vérifier le package Android

   Relevez applicationId dans le build.gradle.kts du module app et saisissez-le dans le champ du package Android de votre application PushPort. Cette connexion ne nécessite ni inscription séparée de l’application Android dans Firebase ni empreintes SHA. Conservez les éventuels paramètres Firebase utilisés pour d’autres fonctionnalités.

3. Activer les API

   Dans le même projet Google Cloud, ouvrez APIs & Services → Library. Vérifiez que Firebase Cloud Messaging API (HTTP v1) et Firebase Management API sont activées. PushPort utilise la première pour envoyer et la seconde pour lire le numéro d’expéditeur du projet.

4. Télécharger la clé JSON privée

   Dans Firebase : Project settings → Service accounts → Firebase Admin SDK → Generate new private key. Le JSON téléchargé contient type: service_account, project_id, client_email et private_key. Le langage sélectionné pour l’exemple ne change pas cette clé.

5. Importer la clé dans PushPort

   Dans le tableau de bord, ouvrez votre application → Paramètres → Firebase. Sélectionnez le JSON téléchargé et importez-le. Vérifiez que Firebase apparaît comme configuré. Ce fichier appartient aux paramètres Android de cette application uniquement.

6. Installer et tester le SDK

   Suivez la section Android SDK ci-dessous. Initialisez avec l’App ID PushPort, lancez l’application, autorisez les notifications et retrouvez l’installation dans Audience. Envoyez d’abord un test à cette installation.

Distinguer les fichiers et les identifiants

En cas d’échec de la configuration Firebase

Accès refusé / 403

Vérifiez le projet et la validité de la clé. Dans Google Cloud IAM, le compte de service doit disposer de Firebase Viewer (roles/firebase.viewer) pour lire le projet et de Firebase Cloud Messaging API Admin (roles/firebasecloudmessaging.admin) pour envoyer. Vérifiez les deux API ci-dessus.

Mauvais fichier JSON

Importez la clé du compte de service, pas google-services.json ni un fichier de client Google OAuth.

Installation ou notification absente

Vérifiez l’App ID, la restriction du package, les services Google Play, le réseau, l’autorisation système et l’abonnement SDK. Firebase Analytics ne contrôle pas la collecte des paramètres régionaux.

05 / Android / Firebase

Installer le SDK Android

Le SDK Android 0.0.5 est publié sur Maven Central. Ajoutez google() et mavenCentral() aux dépôts Gradle, puis implementation("dev.pushport:android-sdk:0.0.5"). Gradle télécharge le SDK et ses dépendances transitives.

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

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

Initialisez le SDK dans votre classe Application et déclarez-la dans AndroidManifest.xml. Si cette classe existe déjà, ajoutez-y l’appel. Avec plusieurs processus, initialisez uniquement dans le processus principal.

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)

• Demandez l’autorisation depuis une Activity visible, après en avoir expliqué l’intérêt.
• Firebase Messaging, WorkManager et les composants du manifeste arrivent avec la dépendance.
• Lancez l’application, autorisez les notifications et vérifiez l’installation dans Audience.

06 / Apple / APNs

Préparer Apple APNs

Le SDK Apple PushPort utilise directement APNs. Il ne nécessite ni application iOS enregistrée dans Firebase, ni Firebase Messaging, ni GoogleService-Info.plist. Vous pouvez utiliser Firebase indépendamment pour d’autres fonctionnalités.

1. Adhésion Apple Developer

   Le téléchargement du SDK ne nécessite pas de compte Apple. Un test APNs réel exige une adhésion active à l’Apple Developer Program, une application signée et un profil de provisionnement adapté.

2. Créer ou vérifier le Bundle ID

   Dans Apple Developer → Certificates, Identifiers & Profiles → Identifiers, sélectionnez ou enregistrez l’App ID explicite correspondant au Bundle Identifier dans Xcode. Activez Push Notifications.

3. Préparer une clé APNs

   Dans Keys, créez une clé avec Apple Push Notification service activé et configurez les restrictions d’environnement et de topic proposées pour l’application. Téléchargez le fichier .p8 : Apple ne permet ce téléchargement qu’une fois.

4. Conserver les quatre éléments

   Notez le Team ID, le Key ID, le Bundle ID et conservez le fichier .p8. Vérifiez les environnements et les topics autorisés ; toutes les nouvelles clés ne couvrent pas nécessairement développement et production.

5. Activer la capability dans Xcode

   Sélectionnez la cible principale → Signing & Capabilities → + Capability → Push Notifications. L’équipe et le profil de signature doivent inclure cet entitlement.

6. Choisir le bon environnement

   Utilisez .sandbox pour un entitlement aps-environment de développement et .production pour la production, TestFlight et l’App Store. L’application, le point d’accès serveur et la portée de la clé doivent correspondre. Passez ensuite à l’intégration SDK.

07 / Apple / APNs

Installer le SDK Apple

Installez le package Swift public sur un Mac avec Xcode. Version minimale : iOS 15.0. Aucun compte CocoaPods, fichier Firebase ou téléchargement manuel de framework n’est nécessaire.

1. Ajouter le package

   Xcode → File → Add Package Dependencies → collez l’URL ci-dessous → Exact Version → 0.0.2. Ajoutez le produit PushPort à la cible principale.

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

Initialiser dans l’app delegate

Utilisez l’App ID des paramètres de votre application PushPort. L’exemple SwiftUI ci-dessous transmet les deux callbacks APNs. Avec UIKit, ajoutez les mêmes appels à l’AppDelegate existant.

Utilisez .sandbox pour un entitlement aps-environment de développement et .production pour la production, TestFlight et l’App Store. L’application, le point d’accès serveur et la portée de la clé doivent correspondre. Passez ensuite à l’intégration 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)

    }

}

Demander l’autorisation

Expliquez l’utilité des notifications puis demandez l’autorisation, par exemple depuis un bouton. L’initialisation n’affiche pas la boîte de dialogue système. Après un refus, l’utilisateur modifie l’autorisation dans Réglages.

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)

        }

    }

}

L’autorisation système et l’abonnement PushPort sont distincts. setSubscribed(false) enregistre un désabonnement ; true ne contourne pas un refus système. Le SDK relève automatiquement les langues de l’application et du système ainsi que le fuseau horaire. setLocale(nil) rétablit le choix automatique. Des notifications APNs déjà envoyées peuvent encore arriver après le désabonnement.

// 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.

Profils, consentement et diagnostic des notifications

Le SDK actuel prend en charge profils confirmés, tags à valeurs textuelles, connexion/déconnexion External ID vérifiée, email/téléphone/position et événements explicitement transmis. Votre backend de confiance fournit les preuves d’identité ; aucune clé API de compte dans l’application. Configurez le consentement avant l’initialisation si nécessaire. Consentement des données et autorisation des notifications sont distincts.

Réception, résultats de l’API de notification, préparation/échecs des images, clics, sessions et durée au premier plan sont persistés puis renvoyés avec accusé des événements. Un retour dans les 60 secondes après un clic est direct ; dans l’heure suivant la réception sans clic, il est estimé influencé. Acceptation fournisseur, préparation SDK et succès API ne prouvent pas une vue humaine.

08 / Apple / APNs

Images et gestion des notifications iOS

Pour les images, ajoutez une cible Notification Service Extension dans Xcode et associez-lui uniquement le produit PushPortNotificationService. L’application principale conserve le produit PushPort.

1. Utiliser la classe de l’extension

   Remplacez la classe générée par la sous-classe ci-dessous. Conservez NSExtensionPrincipalClass à $(PRODUCT_MODULE_NAME).NotificationService.

2. Préparer le contenu de la notification

   Apple SDK 0.0.2 télécharge jusqu’à 5 Mio par défaut et applique le réglage projet 1–20 Mio, plafonné à 10 Mio pour les pièces jointes iOS. JPEG/PNG/GIF et conversion WebP vers PNG si disponible utilisent un décodage borné, 20 secondes au total et 2000 pixels maximum par côté. Les échecs conservent le texte. L’icône provient de l’application installée ; Android small_icon et large_icon ne la remplacent pas.

3. Gérer l’ouverture dans l’application

   onNotificationOpened fournit l’identifiant du message et un éventuel lien HTTPS sûr. L’application décide de la navigation. Un échec de téléchargement ou une expiration de l’extension conserve le texte original.

import PushPortNotificationService



final class NotificationService: PushPortNotificationService {}

Pour les diagnostics de réception et d’images en arrière-plan, activez le même App Group dans l’application et l’extension et la même valeur PushPortAppGroup dans leurs Info.plist. Seuls des fichiers d’événements bornés sont partagés ; les identifiants restent dans l’application. Les événements sont envoyés à sa prochaine synchronisation. Les images seules ne nécessitent pas d’App Group.

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

09 / Web / KMP

Configurer Web Push

Web Push utilise le service push du navigateur et les clés VAPID. Aucun projet Firebase n’est nécessaire. Les routes des fournisseurs Chrome/Edge, Firefox et Safari sont préparées.

1. Enregistrer l’origine du site

   Créez une application ou activez Web. Indiquez l’origine HTTPS exacte sans chemin, par exemple https://example.com. Les sous-domaines sont des origines distinctes.

2. Activer Web Push

   Application → Réglages → Activer Web Push. PushPort génère une paire de clés stable et protège la clé privée sur le serveur. Le SDK reçoit uniquement la clé publique. Conservez les clés utilisées par les abonnements existants.

3. Servir le service worker

   Installez le SDK puis copiez le worker sur votre site. Son URL doit renvoyer du JavaScript de la même origine, jamais une page HTML de secours.

4. Demander l’autorisation au clic

   Initialisez après le chargement, puis demandez l’autorisation directement depuis un bouton. Sur iPhone/iPad, une application Web compatible ajoutée à l’écran d’accueil est requise. Un refus se modifie dans les réglages du navigateur.

10 / Web / KMP

Installer le SDK Web

La version 0.0.2 s’installe comme dépendance npm normale depuis l’archive GitHub. La publication npm attend la configuration du compte éditeur. Copiez node_modules/@pushport/web-sdk/dist/pushport-sw.js vers public/pushport-sw.js pendant la compilation du site.

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;

    });

  });

}

Vous avez déjà un worker ? Importez le worker PushPort copié dans celui-ci et passez serviceWorkerRegistration. Le site contrôle la portée et les mises à jour. Le SDK ne remplace pas un autre worker. Les liens HTTPS des notifications restent dans l’origine du site.

setSubscribed(false) désabonne et synchronise le choix. setLocale(null) rétablit la langue automatique. Vérifiez status().lastSyncedAt et syncError après une modification.

Profils, consentement et diagnostic des notifications

Le SDK actuel prend en charge profils confirmés, tags à valeurs textuelles, connexion/déconnexion External ID vérifiée, email/téléphone/position et événements explicitement transmis. Votre backend de confiance fournit les preuves d’identité ; aucune clé API de compte dans l’application. Configurez le consentement avant l’initialisation si nécessaire. Consentement des données et autorisation des notifications sont distincts.

Réception, résultats de l’API de notification, préparation/échecs des images, clics, sessions et durée au premier plan sont persistés puis renvoyés avec accusé des événements. Un retour dans les 60 secondes après un clic est direct ; dans l’heure suivant la réception sans clic, il est estimé influencé. Acceptation fournisseur, préparation SDK et succès API ne prouvent pas une vue humaine.

Web SDK 0.0.2 télécharge indépendamment la grande image et large_icon HTTPS. Limite par défaut : 5 Mio, réglable de 1–20 Mio dans le projet. Décodage/canvas du navigateur réduit les images à 2000 pixels et les icônes à 256 si disponible. Le serveur d’images externe doit autoriser CORS. L’affichage dépend du navigateur et de l’OS ; les noms Android small_icon ne sont pas des URL Web badge. Mettez à jour le paquet de page et le service worker copié de même origine.

11 / Web / KMP

Connecter Kotlin Multiplatform

KMP réutilise nos SDK natifs Android, Apple et Web sans seconde installation. Aucune application PushPort distincte ni clé supplémentaire n’est nécessaire.

commonMain.dependencies {

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

}

1. Module partagé

   Ajoutez dev.pushport:kmp-sdk:0.0.2 à commonMain. Le SDK Android est transitif. Gardez un client par application, appelé depuis le thread UI/principal.

2. Android

   Utilisez createAndroidPushPort(applicationContext) avec un fournisseur de l’Activity active. Ne conservez pas une Activity détruite.

3. Apple

   Ajoutez PushPort 0.0.2 via SPM, instanciez PushPortKMPBridge() en Swift et transmettez les callbacks APNs. Utilisez createApplePushPort() avec les mêmes App ID et environnement.

4. Web

   Installez le SDK Web, servez son worker depuis la même origine et passez le module à createWebPushPort. Kotlin/Wasm et les notifications natives sur ordinateur ne sont pas inclus.

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)

}

La compilation macOS a réussi, avec un framework Kotlin indépendant lié à une application Swift et au SDK Apple publié. La réception sur appareils et navigateurs est vérifiée séparément.

Profils, consentement et diagnostic des notifications

Le SDK actuel prend en charge profils confirmés, tags à valeurs textuelles, connexion/déconnexion External ID vérifiée, email/téléphone/position et événements explicitement transmis. Votre backend de confiance fournit les preuves d’identité ; aucune clé API de compte dans l’application. Configurez le consentement avant l’initialisation si nécessaire. Consentement des données et autorisation des notifications sont distincts.

Réception, résultats de l’API de notification, préparation/échecs des images, clics, sessions et durée au premier plan sont persistés puis renvoyés avec accusé des événements. Un retour dans les 60 secondes après un clic est direct ; dans l’heure suivant la réception sans clic, il est estimé influencé. Acceptation fournisseur, préparation SDK et succès API ne prouvent pas une vue humaine.

12 / Audience et messages

Comprendre l’audience

Utilisateurs, installations et données collectées

Automatiquement : UUID d’installation, ID utilisateur PushPort distinct, Android ID disponible, jeton FCM, autorisation et abonnement, langue et paramètres régionaux, fuseau, package et versions application/OS/SDK, fabricant/modèle, opérateur, sessions et temps au premier plan. Le backend conserve la dernière IP et le pays approximatif du proxy de confiance. Une synchronisation en arrière-plan ne compte pas comme visite.

Chaque nouvelle installation reçoit un nouveau userId PushPort. Les redémarrages et mises à jour le conservent. Android ID relie uniquement l’historique, sans fusion des utilisateurs ni transfert des tags après réinstallation. Les identifiants existants sont conservés. Un login explicitement vérifié peut relier un compte.

Tags, email, téléphone E.164, coordonnées et événements sont fournis explicitement par votre application. PushPort ne lit pas automatiquement les contacts, IMEI, identifiant publicitaire ou GPS. Les coordonnées de contact n’activent pas l’envoi d’emails/SMS.

Après authentification de son utilisateur, votre backend demande une preuve valable cinq minutes via POST /api/v1/apps/{appId}/identity-tokens avec installationId/externalId, puis renvoie token à l’application. Le jeton de session du propriétaire reste sur le backend. Une connexion échouée ou une preuve expirée exige une nouvelle preuve. Les appels SDK mettent les changements en file ; PushPort.user(context) donne le dernier profil confirmé et status().syncError l’erreur.

Si le consentement est requis, appelez setConsentRequired avant l’initialisation. Consentement aux données et autorisation Android des notifications sont distincts. Le retrait arrête la collecte, la synchronisation et l’affichage PushPort ultérieurs ; il ne rappelle pas les requêtes en cours et ne supprime pas l’historique serveur.

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)

L’audience compte les installations. Une personne avec deux appareils peut apparaître deux fois. Filtrez par langue, paramètres régionaux, pays approximatif et état de l’abonnement ; enregistrez les combinaisons utiles en segments.

Le SDK synchronise les paramètres régionaux de l’application et du système, le fuseau horaire, la version et l’état des notifications. de-DE est un paramètre régional, de une langue. Le pays est estimé par IP et peut être inconnu.

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

• SUBSCRIBED — envoi possible si le jeton et l’autorisation sont disponibles.
• UNSUBSCRIBED / PERMISSION_DENIED — notifications désactivées par l’application ou le système.
• AWAITING_TOKEN / INVALID_TOKEN — aucun jeton utilisable.

13 / Audience et messages

Intégration partenaire et API

Application → Réglages → Clés API. Créez une clé pour le serveur du partenaire et copiez-la immédiatement ; elle ne sera plus affichée. Conservez la clé sur le serveur du partenaire ; ne l’intégrez pas dans une application ou une URL publique. Les applications sont déterminées par userId ; aucun App ID requis. Les clés de compte couvrent vos applications et celles des équipes après acceptation de l’invitation. Les droits sont limités par le rôle actuel : lecture pour les observateurs, envoi pour les expéditeurs, modification des tags également pour les gestionnaires. Les droits par application s’appliquent ; un retrait ou changement de rôle modifie immédiatement l’accès. Une clé d’application reste limitée à son application.

L’API accepte le userId PushPort d’origine au format UUID, sans préfixe ni suffixe. Ce n’est ni un jeton FCM ni un Android ID. Le développeur choisit le paramètre du lien et la décoration de l’ID. Le partenaire retire cette décoration et transmet l’UUID d’origine à l’API.

Lien depuis l’application

Lisez le userId confirmé après une synchronisation réussie. Si le profil manque, attendez la synchronisation et réessayez. L’application construit et ouvre ses liens elle-même ; utilisez un constructeur d’URL pour encoder les valeurs. Lors d’un changement de compte, attendez la confirmation du nouveau profil.

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
}

Rechercher une installation

La recherche accepte un seul ID. Réponse : installId, appId (nom du package Android), customAppName, locale (langue), countryCode (nullable), timezone et type: api. Les applications sont déterminées par userId ; aucun App ID requis. Les clés de compte couvrent vos applications et celles des équipes après acceptation de l’invitation. Les droits sont limités par le rôle actuel : lecture pour les observateurs, envoi pour les expéditeurs, modification des tags également pour les gestionnaires. Les droits par application s’appliquent ; un retrait ou changement de rôle modifie immédiatement l’accès. Une clé d’application reste limitée à son application.

POST /api/v1/partner/getInstall/

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json



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

Envoyer à une liste

Envoyez 1 à 10 000 ID. Les doublons sont supprimés ; les ID inconnus ou étrangers figurent dans excludedUserIds. Aucun résultat : 422. click_uuid accepte un tableau ou une chaîne pour compatibilité. Le titre, texte et lien sont communs à la liste. L’API générale utilise userIds, title, body, imageUrl et clickUrl. Pour plusieurs applications, la réponse contient messages : une tâche avec messageId par application, ainsi que les totaux requestedCount, queuedCount et excludedUserIds. Consultez chaque messageId. Le format reste inchangé pour une seule application.

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"

}

Statut d’envoi

Idempotency-Key est facultatif. Sans cet en-tête, chaque requête crée un nouvel envoi, y compris les tentatives répétées. Si fourni, réutilisez la même clé lors des nouvelles tentatives. Contenu différent avec la même clé : 409. 202 signifie mise en file, pas livraison. Une souscription Android actuelle par userId est sélectionnée ; les souscriptions désactivées sont ignorées. Consultez le statut par messageId avec la même clé. Révoquer une clé n’annule pas les tâches acceptées.

60 requêtes/minute par clé ; corps jusqu’à 2 Mio. scheduledAt : millisecondes Unix, jusqu’à 366 jours. Respectez Retry-After sur 429. accepted : accepté par le fournisseur ; opened : ouvert ; unknown : résultat incertain sans répétition aveugle.

Le SDK PushPort Android 0.0.4+ prend en charge une miniature en couleur indépendante de la grande image. Utilisez large_icon dans CSV/XLSX ou l’API partenaire, et largeIcon dans l’API générale. Indiquez une URL HTTPS publique ou un nom de ressource de l’application. Un carré de 256 × 256 est recommandé. Les SDK OneSignal Android existants acceptent aussi ces champs ; les anciennes versions PushPort les ignorent et conservent la notification habituelle.

small_icon (API générale : smallIcon) est un nom de ressource drawable/mipmap sans extension, par exemple ic_stat_offer. La ressource doit déjà être dans l’APK : silhouette blanche sur fond transparent. Une URL ou une image de la galerie ne peut pas servir d’icône de la barre d’état.

GET /api/v1/public/notifications/MESSAGE_ID

Authorization: Bearer YOUR_API_KEY

Inscription, achat et tags utilisateur

Transmettez le même PushPort userId dans le lien WebView et au serveur partenaire. À réception d’une confirmation d’inscription ou d’achat, le serveur partenaire met à jour les tags via l’API. PushPort ne détecte pas automatiquement les actions sur les sites tiers.

Les tags sont séparés par application. Si une personne utilise plusieurs applications, transmettez le bon App ID et le PushPort userId de cette application. Copiez App ID dans Aperçu → App ID ou Paramètres → Clés API, ou appelez GET /api/v1/public/app avec la clé de l’application. Chaque application utilise sa propre clé. Un App ID différent de celui de la clé renvoie 403. Les anciennes URL sans App ID déterminent toujours l’application à partir de la clé.

Créez une clé d’application avec USER_TAGS_WRITE (Modifier les tags utilisateur). Les clés existantes n’obtiennent pas ce droit automatiquement. PATCH modifie uniquement les tags indiqués : la chaîne "true" active un indicateur, null supprime un tag. Répéter la même requête est sans effet supplémentaire. GET sur le même chemin exige INSTALLATIONS_READ. Un userId inconnu ou appartenant à une autre application renvoie 404 sans créer de profil.

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}}

Jusqu’à 50 tags par utilisateur, clés de 64 caractères et valeurs de 256 maximum. Clés et valeurs sont sensibles à la casse ; les valeurs sont des chaînes, pas des booléens. Si un postback arrive avant l’enregistrement du terminal, conservez-le et réessayez après synchronisation. Gardez la clé API sur votre serveur.

Audience et l’éditeur affichent les tags réellement reçus pour l’application choisie. Cliquez pour ajouter Présent ; choisissez Égal à et une valeur pour une correspondance exacte. Les conditions utilisent ET, maximum 10. Différent de inclut les tags absents. Enregistrez les filtres comme segments. install="true" est ajouté automatiquement, quelle que soit l’autorisation des notifications, y compris aux utilisateurs existants. Ce tag système ne peut être modifié ou supprimé et ne compte pas dans la limite de 50 tags personnalisés.

Pour envoyer à tous sauf aux utilisateurs possédant certains tags, choisissez Exclure les tags et indiquez leurs noms, par exemple reg et dep. Un utilisateur avec l’un de ces tags est exclu quelle que soit sa valeur. Les utilisateurs sans ces deux tags restent dans l’audience. Jusqu’à 10 conditions utilisent ET, aussi dans les automatisations et segments enregistrés. Différent de compare une valeur précise.

Les campagnes planifiées sélectionnent les destinataires au démarrage et revérifient les tags avant chaque envoi. Un utilisateur ne correspondant plus est ignoré avec audience_changed. Un push déjà transmis au fournisseur ne peut pas être rappelé. Les tags ne déclenchent pas de campagne automatiquement : créez puis envoyez ou planifiez une campagne.

Notifications API partenaires

Ouvrez un projet → Paramètres du projet → Divers → Notifications API partenaires. Les deux options sont indépendantes et désactivées par défaut. Enregistrez vos modifications.

1. Marquer les utilisateurs après acceptation d’un push API

   Définit api_managed=true lorsqu’un nouvel envoi via l’API partenaire ou publique est mis en file. Cela ne confirme pas la livraison. Les postbacks et les tests administrateur ne définissent pas ce tag.

2. Exclure automatiquement les utilisateurs marqués des campagnes

   S’applique aux campagnes manuelles et automatiques, y compris aux destinataires en attente. Les pushs API restent autorisés. Les utilisateurs restent visibles dans l’audience.

Sans exclusion automatique, ajoutez une condition d’audience dans une campagne manuelle ou automatique : tag api_managed, Différent de, valeur true. Les utilisateurs sans ce tag restent inclus.

Le tag concerne un utilisateur et ses appareils liés dans un même projet. L’utilisateur reste visible et son statut d’abonnement ne change pas. Les postbacks reg/dep, les requêtes d’installation et les tests administrateur ne définissent pas ce tag. Aucune mise à jour du SDK n’est nécessaire. Les imports et les modifications de tags par l’application ou le partenaire ne peuvent pas remplacer ce tag système.

Un push API planifié définit le tag dès que sa nouvelle requête entre dans la file. Les requêtes invalides ou refusées ne marquent personne. Les destinataires en attente sont revérifiés ; un push déjà transmis au fournisseur ne peut pas être rappelé.

Exemple : après installation, tous reçoivent les campagnes générales. Quand Extendy soumet son premier push API pour un utilisateur, la première option activée définit api_managed=true. Si la seconde option est aussi activée, les campagnes générales cessent pour lui et les pushs API partenaires continuent. Un postback reg ou dep seul ne change pas ce routage.

Tags par postback

Pour une URL couvrant toutes les applications, créez une clé dans Clés API du compte avec le droit de modifier les tags utilisateurs. Choisissez Sans expiration pour une clé permanente. Transmettez la clé dans key, le PushPort userId sans suffixe dans user et l’événement dans tag. L’application est déterminée par userId ; aucun App ID requis. Les tags reg, dep, reg_team1 et buyer_team1 ne nécessitent aucune liste préalable. La clé couvre uniquement les applications que le compte peut gérer. Une clé d’application avec le même droit fonctionne dans sa propre application. Les anciennes clés ppb_ conservent leurs restrictions de tags. user_id est aussi accepté ; n’envoyez pas le véritable Android ID.

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

Utilisez reg et dep pour les envois habituels. Ajoutez des tags distincts comme buyer_team1 ou buyer_extendy pour les différents acheteurs ou le trafic Extendy et configurez l’audience. install reste présent après inscription et dépôt : ajoutez des conditions Absent pour exclure les groupes concernés. Un postback modifie uniquement un tag et n’envoie pas de push. Un tag inconnu n’exclut pas automatiquement un utilisateur des autres envois.

Télécharger OpenAPI JSON ↓

14 / Audience et messages

Automatisations

XLSX jusqu’à 32 Mo ; CSV jusqu’à 1 Mo. Les PNG/JPEG/GIF intégrés dans image_url et large_icon sont enregistrés après validation. Les images dans small_icon deviennent large_icon. Exportez Google Sheets en XLSX ; CSV ne contient pas d’images. Les images existantes sont réutilisées.

Après validation, les images sont enregistrées dans un dossier au nom du fichier ou dans le dossier choisi.

Chaque champ vide reçoit une image aléatoire une seule fois. Des répétitions sont possibles. Les choix restent enregistrés avec les messages.

XLSX jusqu’à 32 Mo ou CSV UTF-8 jusqu’à 1 Mo, 5 000 messages et 200 langues. Emojis acceptés. Choisissez l’ordre ou l’aléatoire dans les réglages.

Colonnes : title, message, language, image_url, url. Titre et message requis ; langue dans la ligne ou par défaut. Icônes Android facultatives : large_icon, small_icon (SDK PushPort 0.0.4+ ou OneSignal).

Formats acceptés

Une langue : title, message. Définissez la langue dans le champ ci-dessous.

Plusieurs langues : title, message, language. Indiquez la langue dans chaque ligne.

Avec images et liens : title, message, language, image_url, url. Images et liens facultatifs.

Si un code de langue n’est pas accepté, vous pouvez confirmer l’exclusion de toutes les lignes correspondantes. Aucun remplacement n’est proposé. Le fichier original reste inchangé.

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

1. Importer un tableau

   Vérifier le fichier

2. Applications

   Vérifier l’audience

3. Heures d’envoi, séparées par des virgules

   Fuseau horaire · UTC · 15:00, 18:00, 21:00

4. Mode horaire

   En mode local, 15:00 correspond à l’heure du fuseau de l’appareil. Les fuseaux inconnus utilisent le fuseau de secours. Les changements d’heure sont respectés.

5. Période

   Les deux dates sont incluses. En mode local, la période suit le fuseau de chaque utilisateur. Une date vide signifie aucune limite.

6. Sélection des messages

   Chaque pool de langue est mélangé. Après le pool, l’automatisation se termine ou commence un nouveau cycle si la répétition est activée.

7. Enregistrer sans démarrer

   Enregistré sans démarrer

8. Démarrer

   Répéter après le dernier message

Après interruption, le créneau passé est ignoré et la séquence avance d’un message. Reprise au prochain créneau futur.

Ouvrez l’automatisation et choisissez Modifier. Mettez d’abord une automatisation active en pause. Modifiez le nom, les messages, images, horaires, dates, audience et répétition. L’enregistrement la laisse en pause : vérifiez l’audience puis choisissez Reprendre. Une automatisation terminée ou arrêtée définitivement ne peut plus être modifiée.

Modifier les messages ou leur sélection commence un nouveau cycle. Le nom, les horaires, l’audience et la répétition conservent la position du message. Les rapports précédents restent disponibles ; un envoi actif garde son ancien message et son audience.

Pour envoyer à tous sauf aux utilisateurs possédant certains tags, choisissez Exclure les tags et indiquez leurs noms, par exemple reg et dep. Un utilisateur avec l’un de ces tags est exclu quelle que soit sa valeur. Les utilisateurs sans ces deux tags restent dans l’audience. Jusqu’à 10 conditions utilisent ET, aussi dans les automatisations et segments enregistrés. Différent de compare une valeur précise.

Ouvrez Messages → Bibliothèque ou le menu du compte. Créez directement un modèle de campagne ou d’automatisation. Ajoutez les messages manuellement, sans tableau obligatoire. Modifiez les modèles depuis leurs cartes. Vous pouvez aussi enregistrer une campagne existante comme modèle. Choisissez le projet lors de l’utilisation, vérifiez les réglages et enregistrez un brouillon ou une automatisation en pause avant de démarrer. Les modèles sont privés ; les modifications et suppressions ne changent pas les copies existantes.

Historique des envois

15 / Audience et messages

Envoyer et programmer

Ouvrez Campagnes dans votre application. Enregistrez un brouillon avec un titre, un message et une audience. Vérifiez le nombre de destinataires éligibles et testez sur votre installation.

Choisissez un envoi immédiat ou une date future. L’heure affichée utilise le fuseau du navigateur et est stockée en UTC. La programmation continue sur le serveur après fermeture de la page.

• Priorité des traductions : paramètres régionaux exacts → langue → texte par défaut.
• Campagnes quotidiennes récurrentes et automatisations à plusieurs horaires sont disponibles. Les automatisations peuvent suivre le fuseau local du destinataire ; la file affiche les dates dans le fuseau de votre navigateur.
• L’annulation arrête les messages en attente, mais ne rappelle pas ceux déjà transmis à FCM.

Bibliothèque de modèles

Ouvrez Messages → Bibliothèque ou le menu du compte. Créez directement un modèle de campagne ou d’automatisation. Ajoutez les messages manuellement, sans tableau obligatoire. Modifiez les modèles depuis leurs cartes. Vous pouvez aussi enregistrer une campagne existante comme modèle. Choisissez le projet lors de l’utilisation, vérifiez les réglages et enregistrez un brouillon ou une automatisation en pause avant de démarrer. Les modèles sont privés ; les modifications et suppressions ne changent pas les copies existantes.

Le texte, les traductions, les liens d’images, les critères et les réglages sont copiés. Les identifiants d’appareils, dates et progression sont exclus. Les images restent partagées : conservez les fichiers sources.

16 / Audience et messages

Images et liens

Ouvrez Galerie dans le projet et sélectionnez plusieurs PNG/JPEG/GIF à la fois. Chaque fichier importé reçoit sa propre URL HTTPS ; les échecs peuvent être réessayés séparément. Choisissez les images dans les campagnes et automatisations pour la grande image ou la miniature Android. Les URL HTTPS publiques externes restent utilisables. Les sections Grandes images et Icônes classent les fichiers selon leur usage. Choisissez la section avant l’importation. Le droit de gestion permet de déplacer les fichiers sans modifier les liens ni les messages existants. Dans l’éditeur, la galerie suit le choix de la grande image ou de la miniature Android. Toutes les images permet de réutiliser chaque fichier. Les icônes de statut restent intégrées à l’application.

PNG, JPEG ou GIF, jusqu’à 5 Mo par fichier. Réduction sans recadrage à 2000 px maximum par côté ; GIF utilise sa première image. Jusqu’à 100 images / 500 Mo par projet. Les fichiers sont publics par leur lien. La limite distincte de téléchargement SDK est de 5 Mio par défaut avec Android SDK 0.0.3+, réglable de 1–20 Mio dans les paramètres du projet. Android SDK 0.0.2 et antérieurs gardent 1 Mio. Les SDK Apple et Web 0.0.2 utilisent aussi 5 Mio par défaut et le réglage projet ; iOS plafonne les pièces jointes à 10 Mio. Voir les guides de plateforme pour CORS Web et l’extension/App Group Apple.

• Le droit d’envoi permet l’importation ; le droit de gestion permet la suppression.
• Supprimer une image invalide son lien dans les messages existants et planifiés. Supprimer le projet retire toutes ses images. Les copies déjà téléchargées sur les appareils restent disponibles.
• Vérifiez l’aperçu et testez sur un appareil.

Pour la grande image, utilisez un paysage 2:1, par exemple 1024 × 512. Le SDK accepte jusqu’à 4096 pixels par côté et 8 millions de pixels au total. La galerie réduit à 2000 pixels maximum par côté. SDK 0.0.4 et antérieurs réduisent les images externes à 1024 ; SDK 0.0.5+ conserve jusqu’à 2000 et accepte les GIF statiques. L’icône de la barre d’état utilise 24 dp : variantes raster de 24, 36, 48, 72 et 96 pixels pour mdpi–xxxhdpi ; une ressource vectorielle de 24 dp convient aussi.

Icônes des notifications Android

Le SDK PushPort Android 0.0.4+ prend en charge une miniature en couleur indépendante de la grande image. Utilisez large_icon dans CSV/XLSX ou l’API partenaire, et largeIcon dans l’API générale. Indiquez une URL HTTPS publique ou un nom de ressource de l’application. Un carré de 256 × 256 est recommandé. Les SDK OneSignal Android existants acceptent aussi ces champs ; les anciennes versions PushPort les ignorent et conservent la notification habituelle.

small_icon (API générale : smallIcon) est un nom de ressource drawable/mipmap sans extension, par exemple ic_stat_offer. La ressource doit déjà être dans l’APK : silhouette blanche sur fond transparent. Une URL ou une image de la galerie ne peut pas servir d’icône de la barre d’état.

Ressources par défaut PushPort : ic_stat_pushport_default et ic_pushport_large_icon_default. Une ressource absente ou un téléchargement échoué conserve le texte et les icônes par défaut. Aucun appel SDK ni autorisation supplémentaire n’est requis. Avec la suppression des ressources inutilisées en release, conservez les ressources choisies dynamiquement dans 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 / Audience et messages

Comprendre les résultats

Un envoi réussi signifie que FCM, APNs ou le service push du navigateur a accepté la requête. Cela ne prouve pas l’affichage sur l’appareil. Les ouvertures signalées, les erreurs et les résultats incertains sont comptés séparément.

Android SDK 0.0.3+ ajoute les rapports de livraison par application : réception SDK, création Android, téléchargement et ajout de l’image avec taille, durée et statut HTTP, clics, erreurs de lancement du lien et de synchronisation. Filtrez par date ou ID utilisateur/installation/message et consultez la chronologie. Acceptation FCM ne confirme pas livraison, création Android ne prouve pas visibilité et lancement du lien ne prouve pas chargement du site. Les anciens SDK fonctionnent sans ces événements. Les inscriptions, dépôts et dépôts répétés doivent venir du partenaire.

• Vérifiez l’abonnement et l’autorisation avant un nouvel essai.
• L’audience de l’aperçu peut différer de celle au moment de l’envoi.
• Comparez l’heure et l’identifiant d’installation lors d’une investigation.

18 / Audience et messages

Résoudre un problème

Si l’installation manque, lancez l’application et vérifiez l’App ID, la connexion au serveur et l’initialisation du SDK. Si elle existe mais reste inéligible, vérifiez l’autorisation, l’abonnement et le jeton.

Si le message est accepté mais invisible, vérifiez le réseau, les réglages de notifications et l’installation ciblée. Pour un problème d’image, ouvrez l’URL sans connexion et vérifiez taille et format.

• Code absent : vérifiez les indésirables et l’adresse, puis attendez une minute avant une nouvelle demande.
• Erreur Firebase : les identifiants d’expéditeur appartiennent-ils au bon projet ?
• Toujours bloqué ? Envoyez l’App ID, l’heure approximative et le résultat attendu via Contact.