Starter-Kit für Telekommunikations-Abonnentendaten und -Segmente

Diese Anleitung beschreibt, wie Sie ein Telekommunikations-Abonnentenprofil in Pushwoosh einrichten und es in funktionierende Segmente umwandeln: Erinnerungen an das Auslaufen von Paketen, Warnungen bei niedrigem Guthaben, Aufladebestätigungen und Willkommensnachrichten beim Roaming. Führen Sie jeden Abschnitt aus, und das erste Segment, das Sie erstellen, wird eine Zielgruppe von mehr als null ergeben, sodass Sie den Support nicht kontaktieren müssen.

Der häufigste Fehler ist der Tag-Typ. Ein Datum, das in einem Integer-Tag gespeichert ist, sieht in der Tag-Liste gut aus und führt stillschweigend dazu, dass jedes Datumssegment null Benutzer zurückgibt. Wählen Sie zuerst die Typen aus und laden Sie dann die Daten.

Voraussetzungen

• Eine Anwendung in Ihrem Pushwoosh-Konto, bei der das SDK integriert ist oder Geräte über die API registriert sind.
• Ein API-Zugriffstoken mit der Berechtigung, Tags zu setzen.
• Unterstützung durch Entwickler für den Server-zu-Server-Aktualisierungsjob.
• Eine Abonnentenkennung, die Sie Pushwoosh zuordnen können: entweder eine User ID (normalerweise die MSISDN, die Telefonnummer des Abonnenten im internationalen Format, oder eine interne Abonnentenkennung) oder die Geräte-HWID.

Wie ein Telekommunikations-Abonnentenprofil aussieht

Die folgende Tabelle listet die Tags auf, die die Standard-Telekommunikationsszenarien abdecken. Erstellen Sie diese vor dem ersten Daten-Upload mit genau diesen Typen.

Tag	Typ	Beispielwert	Was es steuert
msisdn	String	923001234567	Identität und SMS-Targeting
tariff_plan	String	Gold Postpaid	Tarifspezifische Angebote
prepaid_postpaid	String	prepaid	Aufteilung der Basis nach Abrechnungsmodell
balance	Integer	50	Warnungen bei niedrigem Guthaben
bundle_id	String	DATA_5GB_30D	Um welches Paket es sich bei der Erinnerung handelt
bundle_expiry_date	Date	2026-09-20 21:00:00	Erinnerungen an das Auslaufen von Paketen
roaming_status	Boolean	true	Roaming-Willkommensnachrichten und Warnungen vor Roaming-Gebühren

Zwei Zeilen in dieser Tabelle entscheiden darüber, ob die Szenarien überhaupt funktionieren.

• bundle_expiry_date muss ein Date-Tag sein. Nur Date-Tags erhalten die relativen Operatoren, wie z.B. in N bis M Tagen, die ausdrücken, dass „das Paket in drei Tagen abläuft“, ohne das Segment jede Nacht neu berechnen zu müssen.
• bundle_id bleibt vom Ablaufdatum getrennt. Ein Tag enthält das Datum, ein anderer, zu welchem Paket es gehört. Würde man beides in einem Tag speichern, müsste ein String innerhalb des Segments geparst werden, was der Segment-Builder nicht kann.

Warum der Tag-Typ vor dem ersten Upload festgelegt wird

Tags werden automatisch erstellt, wenn ein Wert zum ersten Mal ankommt, und der Typ wird aus diesem ersten Wert abgeleitet. Eine ganze Zahl wird zu Integer, eine Zahl mit einem Dezimalpunkt wird zu Price, ein String wird zu String (oder Date, wenn er einem erkannten Datums-Zeit-Format wie 2024-10-02 22:11 entspricht), ein Array wird zu List und true/false wird zu Boolean.

Die Ableitung schlägt bei Telekommunikationsdaten fehl, da Ablaufdaten normalerweise als Unix-Zeitstempel gesendet werden:

• Sie senden bundle_expiry_date als die Zahl 1758393600. Da es sich um eine ganze Zahl handelt, wird der Tag als Integer-Tag erstellt. Die Werte werden korrekt geladen, der Tag sieht in Ordnung aus, und es wird nie ein Datumsoperator dafür angeboten.
• Der Tag existiert bereits als Integer und Sie wechseln später zum Senden von "2026-09-20". Der Wert kann nicht mehr als Zahl geparst werden und wird daher ohne Fehler verworfen. Die API antwortet weiterhin mit Erfolg, und das Gerät behält seinen alten Wert oder gar keinen.

Beide Fälle enden mit einem Segment, das null Benutzer zurückgibt, und nirgendwo gibt es einen Fehler, der dies erklärt.

Ein Tag-Typ kann nach der Erstellung nicht mehr geändert werden. Um einen falschen Typ zu korrigieren, müssen Sie einen neuen Tag mit dem richtigen Typ erstellen und die Werte neu laden. Der alte Tag bleibt in der Liste, bis Sie ihn löschen.

Um beide Fälle zu verhindern, legen Sie die Typen selbst fest:

1. Öffnen Sie die Seite Tags in Ihrem Control Panel.
2. Klicken Sie auf Tag erstellen.
3. Geben Sie den Tag-Namen ein und wählen Sie seinen Typ aus der Liste. Wiederholen Sie dies für jeden Tag in der obigen Tabelle vor dem ersten Upload.
4. Senden Sie in bulkSetTags create_missing_tags: false. Ein fehlender Tag gibt dann einen Fehler zurück, anstatt mit einem abgeleiteten Typ erstellt zu werden.

Wie das Profil Server-zu-Server aktualisiert wird

Die Profildaten im Telekommunikationsbereich ändern sich täglich, daher werden sie als Batch-Job und nicht über das mobile SDK geladen.

1. Erstellen Sie auf Ihrer Seite das tägliche Delta: Abonnenten, deren Guthaben, Paket oder Roaming-Status sich seit dem letzten Lauf geändert hat. Ein vollständiger Neu-Upload der gesamten Basis ist selten erforderlich und verbraucht Ihr Anfragevolumen.
2. Senden Sie den Batch an bulkSetTags und adressieren Sie Geräte über user_id, wenn die MSISDN Ihre User ID ist, oder andernfalls über hwid. Eine Anfrage enthält viele Geräte, und die Methode erwartet mindestens 50 davon. Für einen einzelnen Abonnenten verwenden Sie stattdessen setTags.
3. Fragen Sie die zurückgegebene request_id mit dem bulkSetTags-Status ab, bis der Job abgeschlossen ist. Fordern Sie ihn mit ?detailed=true an und protokollieren Sie das Ergebnis, denn ein abgeschlossener Job bedeutet nicht, dass jeder Wert akzeptiert wurde.
4. Wiederholen Sie fehlgeschlagene Batches mit derselben Payload. Das Setzen eines Tags ist idempotent: Das zweimalige Senden desselben Wertes führt zum selben Profil.

Tägliche Paket-Aktualisierung

{
  "application": "XXXXX-XXXXX",
  "auth": "your API access token",
  "create_missing_tags": false,
  "devices": [{
    "user_id": "923001234567",
    "tags": {
      "bundle_id": "DATA_5GB_30D",
      "bundle_expiry_date": "2026-09-20 21:00:00",
      "balance": 50,
      "roaming_status": false
    }
  }]
}

Welche Datumsformate ein Date-Tag akzeptiert

Ein Date-Tag speichert einen Unix-Epoch-Zeitstempel in Sekunden. Senden Sie eines der folgenden Formate:

• Einen Epoch-Wert in Sekunden als Zahl: 1758393600.
• Einen Datums-Zeit-String mit Trennzeichen: 2026-09-20 21:00:00, 2026-09-20 21:00 oder 2026-09-20. Ein Datum ohne Zeitangabe bedeutet Mitternacht.
• Einen ISO 8601-String mit einem Offset: 2026-09-20T21:00:00+05:00.

Zwei Formate verhalten sich auf eine Weise, die die meisten Integrationen überrascht:

• Ein String ohne Zeitzone wird als UTC gelesen. Er wird nicht in Ihrer lokalen Zeit gelesen. Ein Paket, das um 21:00 Uhr in Karatschi abläuft, ist 2026-09-20T21:00:00+05:00 oder der entsprechende Epoch-Wert. 2026-09-20 21:00:00 ist in Echtzeit drei Stunden früher, was Abonnenten zwischen den täglichen Erinnerungswellen verschiebt.
• Ein String aus Ziffern ist ein Epoch-Wert, kein Datum. "20260920" ist nicht der 20. September 2026, sondern ein Epoch-Zeitstempel, der auf 1970 verweist. Senden Sie entweder einen echten Epoch-Wert oder einen String mit Trennzeichen.

Ein Wert, der keinem der akzeptierten Formate entspricht, wird verworfen, ohne dass die Anfrage fehlschlägt. Deshalb wird in Schritt 3 oben das Jobergebnis und nicht nur der HTTP-Status überprüft.

Segment-Rezepte

Jedes der folgenden Rezepte ist ein Segment. Öffnen Sie den Abschnitt Segmente, klicken Sie auf Segment erstellen, um den Builder zu öffnen, und fügen Sie dann die aufgelisteten Filter hinzu. Eine vollständige Anleitung zum Builder finden Sie unter Segmente nach Tags erstellen.

Paket läuft in drei Tagen ab

Zielt auf Abonnenten ab, deren aktuelles Paket in drei Tagen ausläuft, sodass die Erinnerung ankommt, während eine Verlängerung noch sinnvoll ist.

• Tag: bundle_expiry_date
• Operator: Öffnen Sie die Operator-Liste, gehen Sie zum Abschnitt RELATIVE DATUMSANGABEN und wählen Sie in N bis M Tagen
• Werte: 3 und 3

Ändern Sie beide Werte auf 1 und 1 für die Erinnerung am letzten Tag. Fügen Sie einen zweiten Filter für bundle_id hinzu, wenn die Nachricht das spezifische Paket benennt.

Verwenden Sie hier nicht die Operatoren aus dem Abschnitt JAHRESTAG

Der Abschnitt JAHRESTAG bietet ist in N Tagen. Dieser Operator vergleicht nur den Tag und den Monat, sodass er jeden Abonnenten erfasst, dessen Paket an diesem Datum in einem beliebigen Jahr abgelaufen ist. Verwenden Sie ihn für Geburtstage, nicht für die Gültigkeit von Paketen.

Niedriges Guthaben

Zielt auf Prepaid-Abonnenten ab, die die nächste Verlängerung nicht mehr bezahlen können.

• Tag: balance, Operator kleiner oder gleich, Wert 50
• Tag: prepaid_postpaid, Operator gleich, Wert prepaid

Beide Bedingungen gehören in dieselbe Gruppe, kombiniert mit UND.

Roaming-Eintritt

Zielt auf Abonnenten ab, die sich gerade im Ausland aufhalten, für eine Willkommensnachricht mit lokalen Tarifen.

• Tag: roaming_status, Operator wahr

Ein Tag-basiertes Segment spiegelt den Zustand zum Zeitpunkt der Kompilierung wider. Wenn die Nachricht in dem Moment versendet werden soll, in dem das Roaming beginnt, lösen Sie eine Customer Journey durch ein Roaming-Event aus, anstatt an dieses Segment zu senden.

Aufladebestätigung und andere Reaktionen

Die Bestätigung einer Aufladung ist eine Reaktion auf die Aktion eines einzelnen Abonnenten, keine Zielgruppe, die zusammengestellt wird. Senden Sie ein benutzerdefiniertes Event von Ihrem Abrechnungssystem mit postEvent und starten Sie davon eine Customer Journey. Dasselbe gilt für den Kauf von Paketen und Tarifänderungen.

Das Segment gibt null Benutzer zurück

Überprüfen Sie diese Punkte in der angegebenen Reihenfolge. Die ersten drei decken die meisten der an den Support gemeldeten Fälle ab.

1. Überprüfen Sie den Tag-Typ auf der Seite „Tags“. Wenn bundle_expiry_date ein Integer ist, wurde nie ein Datumsoperator angewendet und das Segment hat Zahlen verglichen. Erstellen Sie einen Date-Tag und laden Sie die Werte neu.
2. Überprüfen Sie, ob die Werte tatsächlich angekommen sind. Öffnen Sie den User Explorer, suchen Sie einen Abonnenten, von dem Sie wissen, dass er im Batch war, und sehen Sie sich seine Tags an. Ein leerer Tag nach einem erfolgreichen Job bedeutet, dass die Werte aufgrund des Formats abgelehnt wurden, meistens reine Ziffern-Strings oder ein Datum, das keinem Layout entsprach.
3. Überprüfen Sie den Operator-Abschnitt. ist in N Tagen unter JAHRESTAG ignoriert das Jahr. in N bis M Tagen unter RELATIVE DATUMSANGABEN tut dies nicht.
4. Überprüfen Sie die Zeitzone. Ablauf-Zeitstempel, die ohne Offset gesendet werden, werden als UTC gelesen, was einen Abonnenten in den vorherigen oder nächsten Tag Ihres Erinnerungsplans verschieben kann.
5. Berechnen Sie das Segment neu, bevor Sie die Zahl ablesen, damit Sie nicht auf eine zwischengespeicherte Größe schauen. Siehe Segmentgröße berechnen.

Zu berücksichtigende Einschränkungen

• Ein Tag-Typ ist dauerhaft. Planen Sie das Profil vor dem ersten Upload, da die spätere Korrektur eines Typs einen neuen Tag und einen vollständigen Neu-Upload bedeutet.
• Relative Datumsoperatoren sind in High-Speed-Delivery-Segmenten nicht verfügbar. Anwendungen, die für High-Speed Delivery konfiguriert sind, kompilieren ihre Segmente vor, und die relativen Datumsoperatoren werden dort nicht angeboten. Erinnerungen an das Auslaufen von Paketen müssen als gewöhnliche Segmente ausgeführt werden.
• Ein Batch-Job ist nicht in Echtzeit. Segmente sehen das Profil zum Zeitpunkt des letzten erfolgreichen Ladevorgangs. Szenarien, die innerhalb von Sekunden nach einer Guthabenänderung ausgelöst werden müssen, gehören in eine ereignisgesteuerte Journey und nicht in einen nächtlichen Batch.