Unity SDK: Grundlegende Integrationsanleitung

Diese Anleitung führt Sie durch die Integration des Pushwoosh Unity SDK in Ihre Anwendung.

Voraussetzungen

Anforderungen

• Ein Pushwoosh-Konto.
• Ein in Ihrem Konto eingerichtetes Pushwoosh-Projekt.
• Unity 2021.3 oder neuer.
• Für iOS:
  • Eine für den Versand von Push-Benachrichtigungen konfigurierte iOS-Plattform. Wir empfehlen die Verwendung der Token-basierten Authentifizierung als einfachsten Ansatz.
  • Stellen Sie das Gateway auf Sandbox ein, um Push-Benachrichtigungen an einen Simulator zu senden.
• Für Android:
  • Eine konfigurierte Android-Plattform.
  • Die Projektnummer (auch bekannt als Sender ID), die Datei google-services.json und der Paketname aus Ihrem Firebase-Projekt.
  • Ein mit Ihrer Android-Anwendung verbundenes Firebase-Projekt. Folgen Sie bei Bedarf der Firebase-Einrichtungsanleitung.
• Ihr Pushwoosh Application Code und Ihr Pushwoosh Device API Token aus dem Pushwoosh Control Panel.

Integrationsschritte

1. Pushwoosh Unity SDK hinzufügen

UPM über Scoped Registry (empfohlen)

Fügen Sie Folgendes zu Ihrer Packages/manifest.json hinzu:

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

Fügen Sie nur die Plattform-Pakete hinzu, die Sie benötigen. Lassen Sie zum Beispiel com.pushwoosh.unity.android weg, wenn Sie nur auf iOS abzielen.

UPM über Git-URL

Gehen Sie in Unity zu Window > Package Manager > + > Add package from git URL und fügen Sie die folgenden URLs nacheinander hinzu:

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

Laden Sie Pushwoosh.unitypackage von GitHub Releases herunter und importieren Sie es über Assets > Import Package > Custom Package.

2. External Dependency Manager installieren

Das SDK benötigt den External Dependency Manager for Unity (EDM4U), um native Android- und iOS-Abhängigkeiten aufzulösen.

Fügen Sie die folgende Scoped Registry zu Ihrer Packages/manifest.json hinzu:

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

Fügen Sie dann das Paket zu Ihren Abhängigkeiten hinzu:

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

3. Das SDK initialisieren

Erstellen Sie ein PushNotificator.cs-Skript und hängen Sie es an ein beliebiges GameObject in der Szene an:

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();
    }
}

Ersetzen Sie:

• XXXXX-XXXXX durch Ihren Pushwoosh Application Code.
• XXXXXXXXXXXX durch Ihre Firebase-Projektnummer (nur Android).

4. Natives iOS-Setup

4.1 Capabilities

Nachdem Sie das iOS-Projekt aus Unity erstellt haben, öffnen Sie das generierte Xcode-Projekt und fügen Sie die folgenden Capabilities unter Signing & Capabilities hinzu:

• Push Notifications
• Background Modes mit aktivierten Remote notifications

Fügen Sie für Time Sensitive Notifications (iOS 15+) auch die Capability Time Sensitive Notifications hinzu.

4.2 Info.plist

Fügen Sie den Pushwoosh Device API Token zu Ihrer Info.plist hinzu:

Info.plist

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

4.3 Nachverfolgung der Nachrichtenzustellung

Fügen Sie Ihrem Xcode-Projekt ein Notification Service Extension Target hinzu. Dies ist für eine genaue Zustellungsverfolgung und Rich Media auf iOS erforderlich.

Folgen Sie der nativen Anleitung, um das Extension Target hinzuzufügen.

5. Natives Android-Setup

5.1 Firebase-Konfigurationsdatei hinzufügen

Platzieren Sie die Datei google-services.json im Assets-Verzeichnis Ihres Unity-Projekts.

5.2 Pushwoosh-Metadaten hinzufügen

Fügen Sie den Pushwoosh Device API Token zu Ihrer Assets/Plugins/Android/AndroidManifest.xml innerhalb des <application>-Tags hinzu:

AndroidManifest.xml

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

Vorsicht

Stellen Sie sicher, dass der Token Zugriff auf die richtige App in Ihrem Pushwoosh Control Panel hat. Erfahren Sie mehr

6. Das Projekt ausführen

1. Erstellen und führen Sie das Projekt auf Ihrer Zielplattform aus.
2. Erteilen Sie die Erlaubnis für Push-Benachrichtigungen, wenn Sie dazu aufgefordert werden.
3. Gehen Sie zum Pushwoosh Control Panel und senden Sie eine Push-Benachrichtigung.

Erweiterte Integration

In diesem Stadium können Sie Push-Benachrichtigungen senden und empfangen. Die folgenden Abschnitte behandeln die Kernfunktionalität des SDK.

Event-Listener für Push-Benachrichtigungen

Das SDK bietet zwei Event-Listener zur Behandlung von Push-Benachrichtigungen:

• OnPushNotificationsReceived — wird ausgelöst, wenn eine Push-Benachrichtigung ankommt
• OnPushNotificationsOpened — wird ausgelöst, wenn ein Benutzer auf eine Benachrichtigung tippt

Richten Sie diese Listener während der SDK-Initialisierung ein:

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();
}

Benutzerkonfiguration

Personalisieren Sie Push-Benachrichtigungen, indem Sie Benutzer identifizieren und deren Eigenschaften festlegen:

// Benutzer-ID für geräteübergreifendes Tracking festlegen
Pushwoosh.Instance.SetUserId("user-123");

// Benutzer-E-Mail festlegen
Pushwoosh.Instance.SetEmail("user@example.com");

// Benutzer mit ID und E-Mail festlegen
Pushwoosh.Instance.SetUser("user-123", new List<string> { "user@example.com" });

// Bevorzugte Sprache festlegen
Pushwoosh.Instance.SetLanguage("en");

Tags

Tags sind Schlüssel-Wert-Paare, die Geräten zugewiesen werden und die Segmentierung von Benutzern sowie gezielte Nachrichten ermöglichen:

// String-Tag
Pushwoosh.Instance.SetStringTag("favorite_category", "electronics");

// Integer-Tag
Pushwoosh.Instance.SetIntTag("purchase_count", 5);

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

// Alle Tags abrufen
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);
    }
});

Events

Verfolgen Sie Benutzeraktionen, um das Verhalten zu analysieren und automatisierte Nachrichten auszulösen:

// Ein Login-Event verfolgen
Pushwoosh.Instance.PostEvent("login", new Dictionary<string, object> {
    { "username", "user-123" },
    { "login_type", "email" }
});

// Ein Kauf-Event verfolgen
Pushwoosh.Instance.PostEvent("purchase", new Dictionary<string, object> {
    { "product_id", "SKU-001" },
    { "price", 29.99 },
    { "currency", "USD" }
});

Kommunikationseinstellungen

Ermöglichen Sie Benutzern, sich programmgesteuert für oder gegen Push-Benachrichtigungen zu entscheiden:

// Kommunikation aktivieren
Pushwoosh.Instance.SetCommunicationEnabled(true);

// Kommunikation deaktivieren
Pushwoosh.Instance.SetCommunicationEnabled(false);

// Aktuellen Status prüfen
bool isEnabled = Pushwoosh.Instance.IsCommunicationEnabled();

Badge-Verwaltung

Steuern Sie die App-Badge-Nummer auf unterstützten Plattformen:

// Badge auf eine bestimmte Zahl setzen
Pushwoosh.Instance.SetBadgeNumber(3);

// Badge erhöhen
Pushwoosh.Instance.AddBadgeNumber(1);

// Badge löschen
Pushwoosh.Instance.SetBadgeNumber(0);

Fehlerbehebung

Sollten Sie während des Integrationsprozesses auf Probleme stoßen, lesen Sie den Abschnitt Support und Community.