Segmentierungs (Filter) API

Die Segmentierungs (Filter) API verwaltet Filter, also die Bedingungssätze, die ein Segment Ihrer Benutzer definieren. Verwenden Sie sie, um Filter zu erstellen, aufzulisten und zu löschen sowie die Geräte, die einem Filter entsprechen, zur Analyse oder zur Synchronisierung mit einem externen System zu exportieren. Filterbedingungen können Sie in der Segmentierungssprache schreiben.

createFilter

POST https://api.pushwoosh.com/json/1.3/createFilter

Erstellt einen neuen Filter.

Anforderungskörper

Name	Erforderlich	Typ	Beschreibung
auth*	Ja	string	API-Zugriffstoken aus dem Pushwoosh Control Panel.
name*	Ja	string	Filtername.
filter_expression*	Ja	string	Ausdruck, der gemäß den Regeln der Segmentierungssprache erstellt wurde. Beispiel: T(“City”, eq, “Madrid”), um Benutzer zu segmentieren, deren Stadt Madrid ist.
application	Nein	string	Pushwoosh-Anwendungscode, der den Filter auf eine App beschränkt. Lassen Sie ihn weg, es sei denn, Ihr Konto nutzt High-Speed Delivery oder erfordert app-bezogene Filter. Siehe den Hinweis unter der Tabelle.
expiration_date	Nein	string	Ablaufdatum des Filters. Der Filter wird an einem bestimmten Datum automatisch gelöscht, es sei denn, er wird in einem Preset oder einem RSS-Feed verwendet.

Was der Parameter application erstellt

• Ihr Konto hat High-Speed Delivery konfiguriert: ein High-Speed-Filter.
• Keine High-Speed Delivery, aber Ihr Konto erfordert app-bezogene Filter: ein regulärer app-bezogener Filter.
• Keines von beidem: Die Anfrage schlägt mit einem 403-Fehler fehl, der besagt: the application parameter creates a High-Speed Delivery filter, and High-Speed Delivery is not enabled for this account.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

Beispiel

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// Erstellen von Filtern für Zeitzonen
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API-Zugriffstoken aus dem Pushwoosh Control Panel
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

POST https://api.pushwoosh.com/json/1.3/listFilters

Gibt eine Liste der verfügbaren Segmente (Filter) mit ihren Bedingungen zurück.

Anforderungskörper

Name	Erforderlich	Typ	Beschreibung
auth*	Ja	string	API-Zugriffstoken aus dem Pushwoosh Control Panel.
application*	Ja	string	Pushwoosh-Anwendungscode

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

Beispiel

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

POST https://api.pushwoosh.com/json/1.3/deleteFilter

Löscht einen vorhandenen Filter.

Anforderungskörper

Name	Typ	Beschreibung
auth*	string	API-Zugriffstoken aus dem Pushwoosh Control Panel.
name*	string	Filtername.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Beispiel

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API-Zugriffstoken aus dem Pushwoosh Control Panel
    "name": "filter name"
  }
}

exportSegment

POST https://api.pushwoosh.com/api/v2/audience/exportSegment

Eine geplante Anfrage. Exportiert die Liste der Abonnenten, die unter die angegebenen Filterbedingungen fallen.

Anforderungskörper

Name	Erforderlich	Typ	Beschreibung
auth*	Ja	string	API-Zugriffstoken aus dem Pushwoosh Control Panel.
filterExpression*	Ja	string	Filterbedingungen
exportData	Nein	array	Zu exportierende Daten. Mögliche Werte: "hwids", "push_tokens", "users", "tags", "location", "ad_identifiers". Das Einschließen von "location" fügt die Spalten Latitude und Longitude zur exportierten CSV-Datei hinzu. Wenn exportData weggelassen wird, sind Latitude und Longitude standardmäßig im Export enthalten. "ad_identifiers" fügt die Spalten MADID, Email SHA256 und Phone SHA256 hinzu, um eine Quelldatei für Google Customer Match oder Meta Custom Audience zu erstellen – siehe den Hinweis zum Export von Werbekennungen unten.
filterCode	Nein	string	Vorgefertigter Filtercode, kann anstelle von filterExpression verwendet werden. Kann von der /listFilters-API oder der Adressleiste Ihres Browsers bezogen werden, wenn Sie den Filter im Control Panel anzeigen.
applicationCode	Erforderlich, wenn Sie entweder filterExpression oder filterCode verwenden.	string	Pushwoosh-Anwendungscode
generateExport	Nein	boolean	Standardmäßig auf true gesetzt, und eine Antwort enthält einen Link zum Herunterladen der Datei. Wenn false, wird nur die Anzahl der Geräte in der Antwort gesendet.
format	Nein	string	Legt das Format der exportierten Datei fest: „csv“ oder „json_each_line“. Wenn weggelassen, wird die CSV-Datei generiert.
tagsList	Nein	array	Gibt die zu exportierenden Tags an. Um nur die spezifischen Tags zu erhalten, sollte das „exportData“-Array den Wert „tags“ enthalten.
includeWithoutTokens	Nein	boolean	Auf true setzen, um Benutzer ohne Push-Token in die exportierte Datei aufzunehmen. Standard ist false.

200 Erfolgreich

{
  "task_id": "177458"
}

Beispiel

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // erforderlich. API-Zugriffstoken aus dem Pushwoosh Control Panel
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // Filterbedingungen, siehe die Anleitung zur Segmentierungssprache für die Syntax
  "filterCode": "12345-67890",                              // vorgefertigter Filtercode, kann anstelle von filterExpression verwendet werden
  "applicationCode": "00000-AAAAA",                         // Erforderlich, wenn Sie entweder filterExpression oder filterCode verwenden. Pushwoosh-App-Code. Kann von der /listFilters-API-Anfrage oder der Adressleiste Ihres Browsers bezogen werden, wenn Sie den Filter im Control Panel anzeigen.
  "generateExport": true,                                   // wenn false, wird nur die Geräteanzahl in der Antwort gesendet; standardmäßig enthält eine Antwort einen Link zum Herunterladen der CSV-Datei
  "format": "json_each_line",                               // Format der Datei, in der die Daten dargestellt werden sollen: „csv“ – die .csv-Datei wird heruntergeladen; „json“ – eine JSON-Datei mit allen exportierten Geräten; oder „json_each_line“ – eine JSON-Zeile für jedes Gerät. Wenn nicht angegeben, ist CSV das Standardformat.
  "exportData": ["hwids", "tags"],                          // optional. Zu exportierende Daten. Mögliche Werte: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys", "ad_identifiers"
  "tagsList": ["Name", "Level"],                            // optional. Gibt die zu exportierenden Tags an. Um nur die spezifischen Tags zu erhalten, sollte der Wert „tags“ im „exportData“-Array gesendet werden oder „exportData“ leer sein.
  "includeWithoutTokens": true                              // optional. Auf true setzen, um Benutzer ohne Push-Token in die exportierte Datei aufzunehmen. Standard ist false.
}

Hinweis

Eine Referenz zur Segmentierungssprache zum Schreiben von Filterausdrücken finden Sie hier.

Um beispielsweise alle Abonnenten einer bestimmten App zu exportieren, verwenden Sie die folgenden Filterbedingungen:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // API-Zugriffstoken aus dem Pushwoosh Control Panel
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Filterausdruck, der auf das App-Segment verweist
  "applicationCode": "AAAAA-BBBBB"           // Erforderlicher Pushwoosh-App-Code
}

Vorsicht

In der Antwort erhalten Sie die task_id, um die Ergebnisdatei zu erhalten. Rufen Sie dann /exportSegment/result mit dieser task_id im Anforderungskörper auf, um die Ergebnisdatei abzurufen.

exportSegment-Ergebnisse

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

Ruft den Link zur CSV-Datei mit den /exportSegment-Ergebnissen ab.

Anforderungskörper

Name	Typ	Beschreibung
auth*	String	API-Zugriffstoken aus dem Pushwoosh Control Panel.
task_id*	String	Kennung, die Sie in Ihrer /exportSegment-Antwort erhalten haben.

200: OK

{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

Übergeben Sie die in Ihrer /exportSegment-Antwort erhaltene „task_id“ im Anforderungskörper von /exportSegment/result.

In der /exportSegment/result-Antwort erhalten Sie den Parameter „filename“. Folgen Sie dem in diesem Parameterwert angegebenen Link, um automatisch ein ZIP-Archiv herunterzuladen. Entpacken Sie das Archiv, um die CSV- oder JSON-Datei (abhängig vom in Ihrer Anfrage angegebenen „format“) mit den Gerätedaten zu erhalten.

Ab dem 3. April 2025 ist eine Autorisierung zum Herunterladen der Datei erforderlich:

• Wenn Sie über einen Browser herunterladen, melden Sie sich einfach im Pushwoosh Control Panel an, um Zugriff zu erhalten.
• Wenn Sie über Server-Software herunterladen, fügen Sie den folgenden Header in Ihre Anfrage ein: Authorization: Token YOUR_API_TOKEN

Wenn Sie „exportData“ in Ihrer /exportSegment-Anfrage angeben, enthält die heruntergeladene Datei nur die angeforderten Daten. Standardmäßig enthält die Datei die folgenden Benutzerdaten:

Feld	Beschreibung	Beispielwert
Hwid	Hardware-ID eines Geräts	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	User ID, die ein Gerät einem bestimmten Benutzer zuordnet. Wenn keine User ID zugewiesen ist, wird die HWID verwendet.	user8192
Push Token	Eindeutige Kennung, die einem Gerät von Cloud-Messaging-Gateways zugewiesen wird. Mehr erfahren	eeeb2fd7…0fc3547
Type	Plattformtyp (Ganzzahl).	1
Type (humanized)	Plattformtyp (Zeichenkette).	iOS
Age	Wert des Standard-Tags Alter.	29
ApplicationVersion	Wert des Standard-Tags Anwendungsversion.	1.12.0.0
City	Wert des Standard-Tags Stadt.	us, boston
TagName	Wert eines in Ihrem Konto erstellten Tags.	TagValue

Export von Werbekennungen

Fügen Sie „ad_identifiers“ zu exportData hinzu, um eine Datei zu erhalten, die für das direkte Hochladen als Google Customer Match- oder Meta Custom Audience-Quelle formatiert ist. Dieser Wert ist nur optional – er ist niemals standardmäßig enthalten, auch wenn exportData weggelassen wird. Er wirkt sich nur aus, wenn format auf „csv“ gesetzt ist. Eine Anforderung mit „json“ oder „json_each_line“ gibt keinen Fehler zurück, aber die folgenden Spalten werden in diesen Formaten stillschweigend weggelassen.

Feld	Beschreibung
MADID	Mobile Werbe-ID (GAID oder IDFA), normalisiert in Kleinbuchstaben.
Email SHA256	SHA-256-Hash der E-Mail des Benutzers, vor dem Hashing in Kleinbuchstaben umgewandelt und gekürzt.
Phone SHA256	SHA-256-Hash der Telefonnummer des Benutzers im E.164-Format vor dem Hashing.

Eine Zeile für einen Benutzer ohne eine der drei Kennungen wird dennoch exportiert, wobei die Spalten MADID, Email SHA256 und Phone SHA256 leer bleiben.

App-Aktivität pro Benutzer exportieren

Hinweis

Kampagnenstatistiken geben die Anzahl der Öffnungen/Sendungen aggregiert nach Stunde und Plattform zurück. Es gibt keine hwid- oder user_id-Spalte. Um zu sehen, welche Benutzer die App wann geöffnet haben, exportieren Sie stattdessen ein Segment, das auf dem PW_ApplicationOpen-Ereignis basiert.

PW_ApplicationOpen ist nur für Mobilgeräte. Bei einem Webprojekt gibt der Segmentexport keine Zeilen zurück, da das Ereignis dort nie ausgelöst wird.

1. Erstellen Sie einen Filterausdruck für das PW_ApplicationOpen-Ereignis, der auf den von Ihnen benötigten Zeitraum beschränkt ist. Verwenden Sie die Ereignisdatumsoperatoren, zum Beispiel „gestern geöffnet“:

Event("AAAAA-BBBBB", "PW_ApplicationOpen", date daysago eq 1)

2. Rufen Sie /exportSegment mit diesem filterExpression, applicationCode und exportData: ["hwids", "users"] auf.
3. Rufen Sie /exportSegment/result mit der zurückgegebenen task_id auf, um die CSV-Datei mit den Spalten Hwid und User ID für jedes Gerät herunterzuladen, das die App in diesem Zeitraum geöffnet hat.

Vorsicht

User ID enthält die Kennung, die Sie einem Gerät zuweisen. Wenn Sie keine zuweisen, wird auf die HWID zurückgegriffen. Der Export teilt Ihnen mit, wer die App innerhalb des gefilterten Zeitfensters geöffnet hat. Es ist kein Ereignisprotokoll pro Öffnung mit einer Zeitstempelspalte. Erstellen Sie also ein Segment pro Tag (oder Zeitfenster), wenn Sie eine tagesgenaue Granularität benötigen.