Unity SDK: Leitfaden zur Basis-Integration

Dieser Leitfaden 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 tokenbasierten Authentifizierung als einfachsten Ansatz.
  • Stellen Sie das Gateway auf Sandbox ein, um Push-Benachrichtigungen an einen Simulator zu senden.
  • Um das native iOS SDK mit Swift Package Manager zu beziehen: Unity 2021.3.15 oder höher, Target minimum iOS Version auf 15.0 oder höher gesetzt und Zugriff auf github.com, wenn Xcode das Projekt baut. Mit Unity 2021.3.0–2021.3.14 oder einem niedrigeren iOS-Ziel wird das SDK mit CocoaPods hinzugefügt (siehe Festlegen, wie das iOS SDK hinzugefügt wird).
• Für Android:
  • Eine konfigurierte Android-Plattform.
  • Die Projektnummer (auch als Sender ID bekannt), die Datei google-services.json und der Paketname aus Ihrem Firebase-Projekt.
  • Ein mit Ihrer Android-Anwendung verbundenes Firebase-Projekt. Folgen Sie bei Bedarf dem Firebase-Einrichtungsleitfaden.
• 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.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"]
    }
  ]
}

Fügen Sie nur die Plattform-Pakete hinzu, die Sie benötigen. Lassen Sie beispielsweise 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 den GitHub Releases herunter und importieren Sie es über Assets > Import Package > Custom Package.

2. External Dependency Manager installieren

Der Android-Teil des SDK benötigt den External Dependency Manager for Unity (EDM4U), um native Android-Abhängigkeiten aufzulösen. Überspringen Sie diesen Schritt, wenn Sie nur iOS unterstützen.

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. Festlegen, wie das iOS SDK hinzugefügt wird

Standardmäßig bezieht der iOS-Export das native SDK aus dem Swift-Paket Pushwoosh-XCFramework mit Swift Package Manager. Sie benötigen für iOS weder CocoaPods noch EDM4U und führen kein pod install aus.

Um die Quelle des iOS SDK zu ändern oder optionale Module hinzuzufügen, öffnen Sie im Unity Editor Window > Pushwoosh SDK Setup:

• Wählen Sie unter iOS SDK from die Option Swift Package Manager oder CocoaPods.
• Wählen Sie bei Swift Package Manager unter Modules (Swift Package Manager only) die optionalen Module aus, die Ihre App verwendet: PushwooshLiveActivities, PushwooshInboxKit, PushwooshInApp, PushwooshVoIP, PushwooshForegroundPush, PushwooshKeychain, PushwooshGRPC, PushwooshGeozones. Die Module werden mit dem App-Target verknüpft. Um ein Modul in Ihrer eigenen App-Erweiterung zu verwenden, fügen Sie es in Xcode zum Target der Erweiterung hinzu. Mit CocoaPods erfolgt der Export ohne diese Module.

Der Export greift auf CocoaPods zurück, und die Unity-Konsole nennt den Grund, wenn eine der folgenden Bedingungen zutrifft:

• CocoaPods ist in Window > Pushwoosh SDK Setup ausgewählt.
• Das Projekt enthält bereits einen PushwooshXCFramework-Pod, in einer *Dependencies.xml-Datei, die EDM4U liest, oder im Podfile. Um zu Swift Package Manager zu wechseln, entfernen Sie den Pod. Für Geozones entfernen Sie den Pod PushwooshXCFramework/Geozones und wählen PushwooshGeozones in Window > Pushwoosh SDK Setup aus.
• Die Unity-Version ist älter als 2021.3.15.
• Target minimum iOS Version liegt unter 15.0.

Mit CocoaPods ist EDM4U nicht erforderlich. Das SDK führt nach dem Export pod install aus und generiert das Podfile selbst, es sei denn, EDM4U ist installiert und schreibt stattdessen das Podfile. Wenn pod install fehlschlägt, zeigt die Unity-Konsole den Fehler an. Führen Sie pod install im Ordner des exportierten Xcode-Projekts aus.

Wenn Ihre Build-Umgebung github.com nicht erreichen kann, kann Xcode das Swift-Paket nicht auflösen. Wählen Sie für solche Builds CocoaPods in Window > Pushwoosh SDK Setup aus.

Der Export mit Swift Package Manager behält Unity-iPhone.xcworkspace bei, sodass Build-Skripte und CI, die den Workspace bauen, ohne Änderungen funktionieren.

Update von einem CocoaPods-Setup

Wenn Sie auf 6.3.0 oder höher aktualisieren, wechselt ein Projekt, das das iOS SDK über CocoaPods oder EDM4U bezogen hat, zu Swift Package Manager, es sei denn, eine der oben genannten Bedingungen hält es bei CocoaPods.

• Um bei CocoaPods zu bleiben, wählen Sie es in Window > Pushwoosh SDK Setup aus.
• Wenn Sie mit Swift Package Manager in den Ordner eines früheren CocoaPods-Exports exportieren, wird der Pushwoosh-Pod aus dem Podfile entfernt, aber das Xcode-Projekt verweist weiterhin auf Pods und lässt sich nur über Unity-iPhone.xcworkspace bauen. Bauen Sie den Workspace oder exportieren Sie in einen neuen Ordner, um ein Projekt ohne CocoaPods zu erhalten.

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

5. Natives iOS-Setup

5.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 aktivierter Option Remote notifications

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

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

5.3 Nachverfolgung der Nachrichtenzustellung

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

Folgen Sie dem nativen Leitfaden, um das Extension-Ziel hinzuzufügen.

6. Natives Android-Setup

6.1 Firebase-Konfigurationsdatei hinzufügen

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

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

7. Das Projekt ausführen

1. Erstellen und führen Sie das Projekt auf Ihrer Zielplattform aus.
2. Erteilen Sie die Berechtigung 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 Verarbeitung 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 eine Benutzersegmentierung sowie gezieltes Messaging 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 programmatisch für Push-Benachrichtigungen an- oder abzumelden:

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

Wenn ein Push nicht zugestellt wird, suchen Sie den Fehlercode für Ihre Plattform unter Sendefehler, um zu erfahren, was er bedeutet und wie Sie ihn beheben.

Wenn während des Integrationsprozesses Probleme auftreten, lesen Sie den Abschnitt Support und Community.