Guide d'intégration de base du SDK Unity

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

Prérequis

Prérequis

• 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 recommandons d’utiliser l’Authentification basée sur les jetons comme approche la plus simple.
  • Réglez la passerelle sur Sandbox pour envoyer des notifications push à un simulateur.
• 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 paquet 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 de l’appareil Pushwoosh depuis le panneau de contrôle de Pushwoosh.

Étapes d’intégration

1. Ajouter le SDK Unity de Pushwoosh

UPM via Scoped Registry (recommandé)

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

Packages/manifest.json

{
  "dependencies": {
    "com.pushwoosh.unity.core": "6.2.7",
    "com.pushwoosh.unity.android": "6.2.7",
    "com.pushwoosh.unity.ios": "6.2.7"
  },
  "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 versions GitHub et importez-le via Assets > Import Package > Custom Package.

2. Installer le gestionnaire de dépendances externes

Le SDK nécessite le gestionnaire de dépendances externes pour Unity (EDM4U) pour résoudre les dépendances natives Android et 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"]
    }
  ]
}

Ajoutez ensuite le paquet à vos dépendances :

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

3. 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).

4. Configuration native iOS

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

4.2 Info.plist

Ajoutez le jeton d’API de l’appareil Pushwoosh à votre Info.plist :

Info.plist

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

4.3 Suivi de la livraison des messages

Ajoutez une cible d’extension de service de notification à votre projet Xcode. Ceci est nécessaire 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.

5. Configuration native Android

5.1 Ajouter le fichier de configuration Firebase

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

5.2 Ajouter les métadonnées Pushwoosh

Ajoutez le jeton d’API de l’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

6. 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 de 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 ID et 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 attribuées aux appareils, permettant la segmentation des utilisateurs et la messagerie ciblée :

// Tag de type chaîne
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 par programmation :

// 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 vous rencontrez des problèmes lors du processus d’intégration, consultez la section support et communauté.