Tag-Alias-API

Die Device API wird verwendet, um die Tag- und Alias-Informationen eines Geräts serverseitig abzufragen, festzulegen, zu aktualisieren und zu löschen. Achten Sie bei der Verwendung darauf, dass serverseitig gesetzte Tags nicht von der Client-Seite überschrieben werden.

• Wenn Sie mit der Tag- und Alias-Logik nicht vertraut sind, wird empfohlen, nur eine Seite zu verwenden: entweder die Client-Seite oder die Server-Seite.
• Wenn beide Seiten gleichzeitig verwendet werden, stellen Sie sicher, dass Ihre Anwendung die Synchronisierung von Tags und Aliasen korrekt verarbeiten kann.

Ausführliche Informationen zu Tags und Aliasen finden Sie in der API-Dokumentation der entsprechenden Client-Plattform.

• web - tag, alias

Einschränkungen und Regeln für die Tag-Verwendung

• Tag-Mengenbegrenzung: Unter einem einzelnen appkey können Sie bis zu 100 000 Tags erstellen.
• Tag-Längenbegrenzung: Die maximale Länge jedes Tags beträgt 40 Byte. Gültige Zeichen umfassen Buchstaben (Groß-/Kleinschreibung wird berücksichtigt), Zahlen, Unterstriche und chinesische Zeichen.
• Geräte-Tag-Bindungslimit: Jedes Gerät kann mit bis zu 100 Tags verknüpft werden.
• Gerätemengenbegrenzung: Unter einem einzelnen Tag können Sie bis zu 100 000 Geräte hinzufügen.

Wenn Sie einen kostenpflichtigen Tarif nutzen und die Nutzungslimits für einen kostenpflichtigen AppKey anpassen möchten, kontaktieren Sie bitte unser Vertriebsteam unter Sales@engagelab.com.

Einschränkungen und Regeln für die Alias-Verwendung

• Zuordnungsbeziehung zwischen Gerät und Alias: Ein Alias kann nur einem Gerät entsprechen und nicht mehreren Geräten zugeordnet werden. Ebenso kann jedes Gerät innerhalb des appkey-Bereichs nur einem Alias zugeordnet werden und nicht mehreren Aliasen.
• Alias-Mengenbegrenzung: Unter einem einzelnen appkey können Sie bis zu 100 000 Aliase erstellen.
• Alias-Längenbegrenzung: Die maximale Länge jedes Alias beträgt 40 Byte. Gültige Zeichen umfassen Buchstaben (Groß-/Kleinschreibung wird berücksichtigt), Zahlen, Unterstriche und chinesische Zeichen.

Wenn Sie einen kostenpflichtigen Tarif nutzen und die Nutzungslimits für einen kostenpflichtigen AppKey anpassen möchten, kontaktieren Sie bitte unser Vertriebsteam unter Sales@engagelab.com.

API-Übersicht

Die Device API wird verwendet, um die Tag- und Alias-Informationen eines Geräts serverseitig abzufragen, festzulegen, zu aktualisieren und zu löschen.

Sie umfasst drei API-Gruppen: device, tag und alias. Dabei gilt:

• device wird verwendet, um verschiedene Eigenschaften eines Geräts abzufragen/festzulegen, einschließlich tags und alias;
• tag wird verwendet, um Geräte-Tags abzufragen/festzulegen/zu löschen;
• alias wird verwendet, um Geräte-Aliase abzufragen/festzulegen/zu löschen.

Eine weitere wichtige Information, die Sie benötigen, ist die registration ID:

Die registration_id des Geräts wird nach der Client-Integration abgerufen. Einzelheiten finden Sie in der Web-API-Dokumentation.

Die Server-Seite stellt keine API bereit, um den Wert der registration_id des Geräts abzurufen. Entwickler müssen die registration ID von der Client-Seite abrufen und zur Speicherung auf den Entwickler-Server hochladen.

Anzahl der Tags unter einem AppKey abfragen

Endpoint

              
              GET /v4/tags_count

            

Anfragebeispiel

Request Headers

              
              GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Example

              
              curl -X GET http://127.0.0.1/v4/tags_count?tags=tag1&tags=tag2&platform=ios -u "appKey:appSecret"

            

Request Parameters

• tags: Fragt die angegebenen Tag-Strings ab. Erforderlich. In einer einzelnen Anfrage können bis zu 1000 Tags abgefragt werden (tags=tag1&tags=tag2&tags=tag3).
• platform: Fragt die angegebene Plattform ab. Erforderlich. Gültige Werte sind android, ios, hmos und web. Andere Werte sind nicht zulässig.

Antwortbeispiel

• Eine erfolgreiche Antwort gibt ein JSON-Objekt zurück, das ein Feld tagsCount enthält. Dieses ist eine Sammlung von Schlüssel-Wert-Paaren, bei der der Schlüssel der Tag-Name und der Wert die Anzahl unter diesem Tag ist.
• Wenn die Anfrage fehlschlägt, wird ein JSON-Objekt mit Fehlerinformationen zurückgegeben. Das Feld code gibt den Fehlercode an, und das Feld message gibt die Fehlermeldung an.

Erfolgreiche Antwort

              
              {
  "tagsCount": {
    "tag1": 0,
    "tag2": 1,
    "tag3": 2
  }
}

            

Fehlgeschlagene Antwort

              
              {
  "error": {
    "code": 21008,
    "message": "app_key is not a 24 size string or does not exist"
  }
}

            

Alias und Tags eines Geräts abfragen

• Ruft alle Eigenschaften des aktuellen Geräts ab, einschließlich tags und alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Anfragebeispiel

Request Headers

              
              GET /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Parameters

• registration_id: Erforderlich. Die registration_id des Geräts.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              {
  "tags": ["tag1", "tag2"],
  "alias": "alias1"
}

            

• Wenn das statistische Element nicht gefunden werden kann, ist es null; andernfalls ist es der Wert des statistischen Elements.

Alias und Tags eines Geräts festlegen

• Aktualisiert die angegebenen Eigenschaften des aktuellen Geräts. Derzeit werden tags und alias unterstützt.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Anfragebeispiel

Request Headers

              
              POST /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Data

              
              {
  "tags": {
    "add": ["tag1", "tag2"],
    "remove": ["tag3", "tag4"]
  },
  "alias": "alias1"
}

            

Request Parameters

• registration_id: Erforderlich. Die registration_id des Geräts.
• tags: Unterstützt add, remove oder einen leeren String. Wenn der Parameter tags ein leerer String ist, bedeutet dies, dass alle Tags gelöscht werden. add/remove wird verwendet, um die angegebenen Tags hinzuzufügen oder zu entfernen.
• alias: Aktualisiert die Alias-Eigenschaft des Geräts. Wenn der Alias ein leerer String ist, wird der Alias des angegebenen Geräts gelöscht.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              success

            

Fehlgeschlagene Antwort

              
              {
  "error": {
    "code": 27002,
    "message": "unknown error"
  }
}

            

Tag-Liste abfragen

• Ruft die Liste aller Tags in der aktuellen Anwendung ab.

Endpoint

              
              GET /v4/tags/

            

Anfragebeispiel

Request Headers

              
              GET /v4/tags/
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Parameters

• Keine

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              {
  "tags": ["tag1", "tag2"]
}

            

• Wenn das statistische Element nicht gefunden werden kann, ist es null; andernfalls ist es der Wert des statistischen Elements.

Bindungsbeziehung zwischen einem Gerät und einem Tag abfragen

• Fragt ab, ob ein Gerät zu einem Tag gehört.

Endpoint

              
              GET /v4/tags/{tag_value}/registration_ids/{registration_id}

            

Anfragebeispiel

Request Headers

              
              GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Parameters

• tag_value: Erforderlich. Das abzufragende Tag.
• registration_id: Erforderlich. Die registration_id des Geräts.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              {"result": true}

            

Ein Tag aktualisieren

• Fügt Geräte zu einem Tag hinzu oder entfernt sie daraus.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Anfragebeispiel

Request Headers

              
              POST /v4/tags/{tag_value}
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Data

              
              {
  "registration_ids": {
    "add": ["registration_id1", "registration_id2"],
    "remove": ["registration_id1", "registration_id2"]
  }
}

            

Request Parameters

• tag_value: Erforderlich. Das abzufragende Tag.
• action: Operationstyp mit zwei Optionen: "add" und "remove", die angeben, ob diese Anfrage zum Hinzufügen oder Entfernen dient.
• registration_ids: Die registration_id-Werte der Geräte, die hinzugefügt oder entfernt werden sollen.
• add/remove: Unterstützt jeweils bis zu 1000 Einträge.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              success

            

Fehlgeschlagene Antwort

              
              {
  "error": {
    "code": 27005,
    "message": "registration id is illegal",
    "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}"
  }
}

            

Ein Tag löschen

Löscht ein Tag und die Zuordnung zwischen dem Tag und Geräten.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Anfragebeispiel

Request Headers

              
              DELETE /v4/tags/{tag_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Parameters

• tag_value: Erforderlich. Das abzufragende Tag.
• platform: Optional. Wenn ausgelassen, sind standardmäßig alle Plattformen ausgewählt.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              success

            

Fehlgeschlagene Antwort

              
              {
  "error": {
    "code": 27002,
    "message": "unknown error"
  }
}

            

Einen Alias abfragen (Bindungsbeziehung mit einem Gerät)

              
              GET /v4/aliases/{alias_value}
Get the device under the specified alias.

            

Einen Alias abfragen

• Ruft das Gerät unter dem angegebenen Alias ab.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Anfragebeispiel

Request Headers

              
              GET /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Parameters

• alias_value: Erforderlich. Der abzufragende Alias.
• platform: Optional. Wenn ausgelassen, sind standardmäßig alle Plattformen ausgewählt.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              {
  "registration_ids": ["registration_id1", "registration_id2"]
}

            

• Wenn das statistische Element nicht gefunden werden kann, ist es null; andernfalls ist es der Wert des statistischen Elements.

Einen Alias löschen

Löscht einen Alias und die Bindungsbeziehung zwischen dem Alias und Geräten.

              
              DELETE /v4/aliases/{alias_value}

            

Anfragebeispiel

Request Headers

              
              DELETE /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Parameters

• alias_value: Erforderlich. Der zu löschende Alias.
• platform: Optional. Wenn ausgelassen, sind standardmäßig alle Plattformen ausgewählt.

Antwortbeispiel

• Erfolg

              
              success

            

• Fehler

              
              {
  "error": {
    "code": 27002,
    "message": "unknown error"
  }
}

            

Online-Status des Benutzers abrufen

Endpoint

              
              POST /v4/devices/status/

            

Anfragebeispiel

Request Headers

              
              POST /v4/devices/status/
Authorization: Basic (base64 auth string)
Accept: application/json

            

Request Data

              
              {
  "registration_ids": [
    "010b81b3582",
    "0207870f1b8",
    "0207870f9b8"
  ]
}

            

Request Parameters

• registration_ids: Die registration_id-Werte der Benutzer, für die der Online-Status benötigt wird. Pro Abfrage werden bis zu 1000 registration_id-Werte unterstützt.
• Diese API kann nur für AppKeys aufgerufen werden, die diesen Dienst beantragt und aktiviert haben.

Antwortbeispiel

Erfolgreiche Antwort

              
              HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

            

Response Data

              
              [
  {
    "regid": "010b81b3582",
    "online": true
  },
  {
    "regid": "0207870f1b8",
    "online": false,
    "last_online_time": "2014-12-16 10:57:07"
  },
  {
    "regid": "0207870f9b8",
    "online": false
  }
]

            

Response Data

• online
  • true: in den letzten 10 Minuten online
  • false: in den letzten 10 Minuten nicht online
• last_online_time
  • wenn online true ist, wird dieses Feld nicht zurückgegeben
  • wenn online false ist und dieses Feld nicht zurückgegeben wird, bedeutet dies, dass die letzte Online-Zeit mehr als zwei Tage zurückliegt
• Bei ungültigen regid-Werten oder regid-Werten, die nicht zum appkey gehören, schlägt die Validierung fehl.

API zur Abfrage von Tag-/Alias-Kontingentinformationen

Fragt die relevanten Kontingentinformationen für den angegebenen AppKey, die Plattform und das Tag ab. Es können nicht mehr als 1000 Tags gleichzeitig abgefragt werden.

Endpoint

              
              GET /v4/tags/quota-info?tags=tag1&platform=android
Authorization: Basic (base64 auth string)
Accept: application/json

            

Anfragebeispiel

              
              curl --location 'https://webpushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

            

Erfolgreiche Antwort

              
              {
  "data": {
    "totalTagQuota": 100000,
    "useTagQuota": 1,
    "totalAliasQuota": 100000,
    "useAliasQuota": 3,
    "tagUidQuotaDetail": [
      {
        "tagName": "tag1",
        "totalUidQuota": 100000,
        "useUidQuota": 0
      },
      {
        "tagName": "tag2",
        "totalUidQuota": 100000,
        "useUidQuota": 0
      }
    ]
  }
}

            

Beschreibungen der Antwortfelder:

• totalTagQuota: Gibt das Gesamtkontingent für die Anzahl der Tags unter der Anwendung an.
• useTagQuota: Gibt das verwendete Tag-Kontingent an.
• totalAliasQuota: Gibt das Gesamtkontingent für die Anzahl der Aliase unter der Anwendung an.
• useAliasQuota: Gibt das verwendete Alias-Kontingent an.
• tagUidQuota: Gibt das Kontingent für die Anzahl der Geräte unter einem einzelnen Tag an.
• useUidQuota: Gibt die detaillierte Anzahl der an jedes Tag gebundenen Geräte an.

Fehlgeschlagene Antwort

              
              {
  "error": {
    "code": 27002,
    "message": "Invalid parameters"
  }
}

            

HTTP-Statuscodes

Referenzdokument: Http-Status-Code

Geschäftsantwortcodes