Guide d'intégration de base du SDK Unity

Ce guide vous explique comment intégrer le SDK Pushwoosh pour Unity dans votre application.

Prérequis

Exigences

• Un compte Pushwoosh.
• Un projet Pushwoosh configuré dans votre compte.
• Unity 2021.3 ou une version ultérieure.
• Pour iOS :
  • Une plateforme iOS configurée pour envoyer des notifications push. Nous vous recommandons d’utiliser l’authentification basée sur un jeton comme approche la plus simple.
  • Réglez la passerelle sur Sandbox pour envoyer des pushes à un simulateur.
  • Pour obtenir le SDK iOS natif avec Swift Package Manager : Unity 2021.3.15 ou version ultérieure, Target minimum iOS Version définie sur 15.0 ou plus, et un accès à github.com lorsque Xcode compile le projet. Avec Unity 2021.3.0–2021.3.14 ou une cible iOS inférieure, le SDK est ajouté avec CocoaPods (voir Choisir comment le SDK iOS est ajouté).
• Pour Android :
  • Une plateforme Android configurée.
  • Le numéro de projet (également connu sous le nom d’ID d’expéditeur), le fichier google-services.json et le nom du package de votre projet Firebase.
  • Un projet Firebase connecté à votre application Android. Suivez le guide de configuration de Firebase si nécessaire.
• Votre Code d'Application Pushwoosh et votre Jeton d’API d’Appareil Pushwoosh depuis le Panneau de Contrôle Pushwoosh.

Étapes d’intégration

1. Ajouter le SDK Pushwoosh pour Unity

UPM via Scoped Registry (recommandé)

Ajoutez ce qui suit à votre fichier Packages/manifest.json :

Packages/manifest.json

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.3.0",
    "com.pushwoosh.unity.android": "6.3.0",
    "com.pushwoosh.unity.ios": "6.3.0"
  },
  "scopedRegistries": [
    {
      "name": "npmjs",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pushwoosh"]
    }
  ]
}

N’ajoutez que les paquets de plateforme dont vous avez besoin. Par exemple, omettez com.pushwoosh.unity.android si vous ne ciblez que iOS.

UPM via URL Git

Dans Unity, allez dans Window > Package Manager > + > Add package from git URL et ajoutez les URL suivantes une par une :

https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.core
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.android
https://github.com/Pushwoosh/pushwoosh-unity.git?path=com.pushwoosh.unity.ios

.unitypackage

Téléchargez Pushwoosh.unitypackage depuis les Releases GitHub et importez-le via Assets > Import Package > Custom Package.

2. Installer l’External Dependency Manager

La partie Android du SDK nécessite External Dependency Manager for Unity (EDM4U) pour résoudre les dépendances Android natives. Ignorez cette étape si vous ciblez uniquement iOS.

Ajoutez le registre de portée suivant à votre Packages/manifest.json :

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": ["com.google.external-dependency-manager"]
    }
  ]
}

Ensuite, ajoutez le paquet à vos dépendances :

"com.google.external-dependency-manager": "1.2.183"

3. Choisir comment le SDK iOS est ajouté

Par défaut, l’export iOS récupère le SDK natif depuis le package Swift Pushwoosh-XCFramework avec Swift Package Manager. Vous n’avez besoin ni de CocoaPods ni d’EDM4U pour iOS, et vous n’exécutez pas pod install.

Pour changer la source du SDK iOS ou ajouter des modules optionnels, ouvrez Window > Pushwoosh SDK Setup dans l’éditeur Unity :

• Dans iOS SDK from, sélectionnez Swift Package Manager ou CocoaPods.
• Avec Swift Package Manager, sous Modules (Swift Package Manager only), sélectionnez les modules optionnels utilisés par votre application : PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. Les modules sont liés à la cible de l’application. Pour utiliser un module dans votre propre extension d’application, ajoutez-le à la cible de l’extension dans Xcode. Avec CocoaPods, l’export se fait sans ces modules.

L’export revient à CocoaPods, et la console Unity indique la raison, dans l’un des cas suivants :

• CocoaPods est sélectionné dans Window > Pushwoosh SDK Setup.
• Le projet contient déjà un pod PushwooshXCFramework, dans un fichier *Dependencies.xml lu par EDM4U ou dans le Podfile. Pour passer à Swift Package Manager, supprimez ce pod. Pour Geozones, supprimez le pod PushwooshXCFramework/Geozones et sélectionnez PushwooshGeozones dans Window > Pushwoosh SDK Setup.
• La version d’Unity est antérieure à 2021.3.15.
• Target minimum iOS Version est inférieure à 15.0.

Avec CocoaPods, EDM4U n’est pas requis. Le SDK exécute pod install après l’export et génère lui-même le Podfile, sauf si EDM4U est installé et écrit le Podfile à sa place. Si pod install échoue, la console Unity affiche l’erreur. Exécutez pod install dans le dossier du projet Xcode exporté.

Si votre environnement de build ne peut pas accéder à github.com, Xcode ne peut pas résoudre le package Swift. Sélectionnez CocoaPods dans Window > Pushwoosh SDK Setup pour ces builds.

L’export Swift Package Manager conserve Unity-iPhone.xcworkspace : les scripts de build et la CI qui compilent le workspace fonctionnent sans modification.

Mise à jour depuis une configuration CocoaPods

Lors de la mise à jour vers la version 6.3.0 ou ultérieure, un projet qui obtenait le SDK iOS via CocoaPods ou EDM4U passe à Swift Package Manager, sauf si l’une des conditions ci-dessus le maintient sur CocoaPods.

• Pour conserver CocoaPods, sélectionnez-le dans Window > Pushwoosh SDK Setup.
• Si vous exportez avec Swift Package Manager dans le dossier d’un précédent export CocoaPods, le pod Pushwoosh est supprimé du Podfile, mais le projet Xcode référence toujours Pods et ne se compile qu’à partir de Unity-iPhone.xcworkspace. Compilez le workspace ou exportez dans un nouveau dossier pour obtenir un projet sans CocoaPods.

4. Initialiser le SDK

Créez un script PushNotificator.cs et attachez-le à n’importe quel GameObject de la scène :

PushNotificator.cs

using UnityEngine;
using System.Collections.Generic;

public class PushNotificator : MonoBehaviour
{
    void Start()
    {
        Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
        Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

        Pushwoosh.Instance.OnRegisteredForPushNotifications += (token) => {
            Debug.Log("Push token: " + token);
        };

        Pushwoosh.Instance.OnFailedToRegisteredForPushNotifications += (error) => {
            Debug.Log("Registration failed: " + error);
        };

        Pushwoosh.Instance.RegisterForPushNotifications();
    }
}

Remplacez :

• XXXXX-XXXXX par votre Code d’Application Pushwoosh.
• XXXXXXXXXXXX par votre numéro de projet Firebase (Android uniquement).

5. Configuration native pour iOS

5.1 Capacités

Après avoir compilé le projet iOS depuis Unity, ouvrez le projet Xcode généré et ajoutez les capacités suivantes dans Signing & Capabilities :

• Notifications Push
• Modes d’arrière-plan avec Notifications à distance coché

Pour les notifications urgentes (iOS 15+), ajoutez également la capacité Time Sensitive Notifications.

5.2 Info.plist

Ajoutez le Jeton d’API d’Appareil Pushwoosh à votre Info.plist :

Info.plist

<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>

5.3 Suivi de la livraison des messages

Ajoutez une cible d’extension de service de notification à votre projet Xcode. Ceci est requis pour un suivi précis de la livraison et pour les Rich Media sur iOS.

Suivez le guide natif pour ajouter la cible d’extension.

6. Configuration native pour Android

6.1 Ajouter le fichier de configuration Firebase

Placez le fichier google-services.json dans le répertoire Assets de votre projet Unity.

6.2 Ajouter les métadonnées Pushwoosh

Ajoutez le Jeton d’API d’Appareil Pushwoosh à votre Assets/Plugins/Android/AndroidManifest.xml à l’intérieur de la balise <application> :

AndroidManifest.xml

<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />

Attention

Assurez-vous de donner au jeton l’accès à la bonne application dans votre Panneau de Contrôle Pushwoosh. En savoir plus

7. Exécuter le projet

1. Compilez et exécutez le projet sur votre plateforme cible.
2. Accordez l’autorisation pour les notifications push lorsque vous y êtes invité.
3. Allez dans le Panneau de Contrôle Pushwoosh et envoyez une notification push.

Intégration étendue

À ce stade, vous pouvez envoyer et recevoir des notifications push. Les sections ci-dessous couvrent les fonctionnalités de base du SDK.

Écouteurs d’événements de notification push

Le SDK fournit deux écouteurs d’événements pour gérer les notifications push :

• OnPushNotificationsReceived — déclenché lorsqu’une notification push arrive
• OnPushNotificationsOpened — déclenché lorsqu’un utilisateur appuie sur une notification

Configurez ces écouteurs lors de l’initialisation du SDK :

PushNotificator.cs

void Start()
{
    Pushwoosh.ApplicationCode = "XXXXX-XXXXX";
    Pushwoosh.FcmProjectNumber = "XXXXXXXXXXXX";

    Pushwoosh.Instance.OnPushNotificationsReceived += (payload) => {
        Debug.Log("Push received: " + payload);
    };

    Pushwoosh.Instance.OnPushNotificationsOpened += (payload) => {
        Debug.Log("Push opened: " + payload);
    };

    Pushwoosh.Instance.RegisterForPushNotifications();
}

Configuration de l’utilisateur

Personnalisez les notifications push en identifiant les utilisateurs et en définissant leurs propriétés :

// Définir l'ID utilisateur pour le suivi multi-appareils
Pushwoosh.Instance.SetUserId("user-123");

// Définir l'e-mail de l'utilisateur
Pushwoosh.Instance.SetEmail("user@example.com");

// Définir l'utilisateur avec à la fois un ID et un e-mail
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// Définir la langue préférée
Pushwoosh.Instance.SetLanguage("en");

Tags

Les tags sont des paires clé-valeur assignées aux appareils, permettant la segmentation des utilisateurs et l’envoi de messages ciblés :

// Tag de type chaîne de caractères
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// Tag de type entier
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

// Tag de type liste
Pushwoosh.Instance.SetListTag("interests", new List<object> { "sports", "music", "tech" });

// Obtenir tous les tags
Pushwoosh.Instance.GetTags((tags, error) => {
    if (error != null) {
        Debug.Log("Error: " + error.Message);
        return;
    }
    foreach (var tag in tags) {
        Debug.Log(tag.Key + ": " + tag.Value);
    }
});

Événements

Suivez les actions des utilisateurs pour analyser leur comportement et déclencher des messages automatisés :

// Suivre un événement de connexion
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// Suivre un événement d'achat
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

Préférences de communication

Permettez aux utilisateurs d’accepter ou de refuser les notifications push de manière programmatique :

// Activer la communication
Pushwoosh.Instance.SetCommunicationEnabled(true);

// Désactiver la communication
Pushwoosh.Instance.SetCommunicationEnabled(false);

// Vérifier l'état actuel
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

Gestion des badges

Contrôlez le numéro du badge de l’application sur les plateformes prises en charge :

// Définir le badge à un nombre spécifique
Pushwoosh.Instance.SetBadgeNumber(3);

// Incrémenter le badge
Pushwoosh.Instance.AddBadgeNumber(1);

// Effacer le badge
Pushwoosh.Instance.SetBadgeNumber(0);

Dépannage

Si un push n’est pas délivré, recherchez le code d’erreur de votre plateforme dans Erreurs d’envoi pour savoir ce qu’il signifie et comment le corriger.

Si vous rencontrez des problèmes lors du processus d’intégration, consultez la section support et communauté.