Documentation

01 / Connecter l’application

Créer une application

Connectez-vous avec Google ou une adresse email vérifiée et un mot de passe. Dans Applications, créez une application et sélectionnez Android. Les paramètres iOS et Web peuvent être enregistrés pour plus tard.

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

• Une application Android avec API 23 ou supérieure.
• Un appareil de test avec les services Google Play et un accès réseau.
• L’accès au projet Firebase de l’application.

02 / Connecter l’application

Connecter Firebase

Ouvrez le bon projet dans Firebase. Dans Project settings → Service accounts, créez une clé JSON privée. Importez-la dans les paramètres Android de l’application PushPort correspondante.

La clé privée reste sur le serveur : ne l’ajoutez pas au projet Android. Cette intégration PushPort ne nécessite ni google-services.json ni le plugin Gradle Google Services. L’intégration Firebase indépendante de votre application peut rester.

• Utilisez les identifiants du bon projet Firebase.
• Toute restriction de package doit correspondre à l’applicationId Android.
• Firebase Analytics n’est pas nécessaire aux données régionales.

03 / Connecter l’application

Installer le SDK Android

Le SDK 0.3.0 est actuellement fourni sous forme de dépôt Maven, pas via Maven Central. Demandez la version à l’assistance et ajoutez le chemin du dépôt dans Gradle. Un fichier AAR seul ne contient pas les métadonnées des dépendances transitives.

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

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

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.

04 / Gérer les messages

Comprendre l’audience

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.

05 / Gérer les 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.
• Les envois ponctuels sont disponibles ; les récurrences et heures locales par destinataire ne le sont pas encore.
• L’annulation arrête les messages en attente, mais ne rappelle pas ceux déjà transmis à FCM.

06 / Gérer les messages

Images et liens

Utilisez une URL HTTPS publique pour l’image et, si besoin, un lien de destination HTTPS. Le SDK 0.3.0 affiche d’abord le texte, puis ajoute l’image si son téléchargement réussit.

Formats acceptés : PNG, JPEG et WebP jusqu’à 1 Mio, 4096 pixels maximum par côté et 8 millions de pixels au total. Les liens nécessitant une connexion ou visant un réseau privé ne conviennent pas.

• L’image doit rester accessible au moment de l’envoi.
• Testez l’image et la destination sur un vrai appareil.
• L’échec de l’image n’empêche pas nécessairement l’affichage du texte.

07 / Vérifier et comprendre

Comprendre les résultats

L’acceptation par FCM signifie que le fournisseur a accepté la requête. Elle ne prouve pas l’affichage sur l’appareil. Les ouvertures sont comptées séparément lorsque le SDK signale un appui.

Examinez ensemble le résultat de la campagne et l’état de l’installation. Un jeton invalide diffère d’une erreur temporaire du fournisseur. Un résultat incertain n’est pas renvoyé aveuglément pour éviter les doublons.

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

08 / Vérifier et comprendre

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.