Tag-Alias-API

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

• Wenn Sie mit der Logik von Tags und Aliasen nicht vertraut sind, wird empfohlen, entweder nur die Client-Seite oder nur die Server-Seite zu verwenden.
• 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 für die entsprechende Client-Plattform.

• Android - Tag, Alias
• iOS - Tag, Alias
• HarmonyOS - 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 unterschieden), Zahlen, Unterstriche und chinesische Zeichen.
• Geräte-Tag-Bindungslimit: Jedes Gerät kann mit bis zu 100 Tags verknüpft werden.
• Geräteanzahl-Limit: 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 Ihren kostenpflichtigen AppKey anpassen möchten, wenden Sie sich bitte an unser Business-Team unter Sales@engagelab.com.

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

• Zuordnung zwischen Gerät und Alias: Ein Alias kann nur einem Gerät entsprechen und nicht mehreren Geräten zugeordnet sein. Ebenso kann innerhalb des Geltungsbereichs eines AppKey jedes Gerät nur einem Alias zugeordnet werden und nicht mehreren Aliasen.
• Alias-Längenbegrenzung: Die maximale Länge jedes Alias beträgt 40 Byte. Gültige Zeichen umfassen Buchstaben (Groß-/Kleinschreibung wird unterschieden), Zahlen, Unterstriche und chinesische Zeichen.

Wenn Sie einen kostenpflichtigen Tarif nutzen und die Nutzungslimits für Ihren kostenpflichtigen AppKey anpassen möchten, wenden Sie sich bitte an unser Business-Team unter Sales@engagelab.com.

API-Übersicht

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

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

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

Eine weitere wichtige erforderliche Information ist die Registration ID:

Die registration_id des Geräts wird nach der Client-Integration erhalten. Details finden Sie in der API-Dokumentation für Android, iOS und HarmonyOS.

Die Server-Seite stellt keine API bereit, um den Wert der Geräte-registration_id zu erhalten. Entwickler müssen die Registration ID auf 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 Header

              
              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. Es können bis zu 1 000 Tags gleichzeitig abgefragt werden (tags=tag1&tags=tag2&tags=tag3).
• platform: Fragt die angegebene Plattform ab. Erforderlich. Gültige Werte sind android, ios und hmos. Andere Werte sind nicht zulässig.

Antwortbeispiel

• Eine erfolgreiche Antwort gibt ein JSON-Objekt mit einem Feld tagsCount zurück, das eine Sammlung von Schlüssel-Wert-Paaren ist, wobei 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.

Successful Response

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

            

Failed Response

              
              {
  "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 Attribute des aktuellen Geräts ab, einschließlich tags und alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Anfragebeispiel

Request Header

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

            

Request Parameters

• registration_id: Erforderlich. Die Geräte-registration_id.

Antwortbeispiel

Successful Response

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

            

Response Data

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

            

• Wenn ein Statistikelement nicht gefunden wird, ist es null; andernfalls ist es der Wert des Statistikelements.

Alias und Tags eines Geräts festlegen

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

Endpoint

              
              POST /v4/devices/{registration_id}

            

Anfragebeispiel

Request Header

              
              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 Geräte-registration_id.
• tags: Unterstützt add, remove oder einen leeren String. Wenn der Parameter tags ein leerer String ist, werden alle Tags gelöscht. add/remove bedeutet, die angegebenen Tags hinzuzufügen oder zu entfernen.
• alias: Aktualisiert das Alias-Attribut des Geräts. Wenn der Alias ein leerer String ist, wird der Alias des angegebenen Geräts gelöscht.

Antwortbeispiel

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Tag-Liste abfragen

• Ruft die Liste aller Tags für die aktuelle Anwendung ab.

Endpoint

              
              GET /v4/tags/

            

Anfragebeispiel

Request Header

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

            

Request Parameters

• Keine

Anfragebeispiel

Successful Response

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

            

Response Data

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

            

• Wenn ein Statistikelement nicht gefunden wird, ist es null; andernfalls ist es der Wert des Statistikelements.

Verknüpfungsbeziehung zwischen einem Gerät und einem Tag abfragen

• Fragt ab, ob sich ein Gerät unter einem Tag befindet.

Endpoint

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

            

Anfragebeispiel

Request Header

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

            

Request Parameters

• tag_value: Erforderlich. Der abzufragende Tag.
• registration_id: Erforderlich. Die Geräte-registration_id.

Antwortbeispiel

Successful Response

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

            

Response Data

              
              {
  "result": true
}

            

Einen Tag aktualisieren

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

Endpoint

              
              POST /v4/tags/{tag_value}

            

Anfragebeispiel

Request Header

              
              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. Der abzufragende Tag.
• action: Vorgangstyp mit zwei Optionen: add und remove, die angeben, ob diese Anfrage Geräte hinzufügt oder entfernt.
• registration_ids: Die Geräte-registration_id-Werte, die hinzugefügt oder entfernt werden sollen.
• add/remove: Unterstützt jeweils bis zu 1 000 Einträge.

Antwortbeispiel

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Einen Tag löschen

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

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Anfragebeispiel

Request Header

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

            

Request Parameters

• tag_value: Erforderlich. Der abzufragende Tag.
• platform: Optional. Wenn nicht angegeben, werden standardmäßig alle Plattformen verwendet.

Antwortbeispiel

Successful Response

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

            

Response Data

              
              success

            

Failed Response

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

            

Alias abfragen (Verknüpfungsbeziehung mit Geräten)

              
              GET /v4/aliases/{alias_value}
Ruft die Geräte unter dem angegebenen Alias ab.

            

Alias abfragen

• Ruft die Geräte unter dem angegebenen Alias ab.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Anfragebeispiel

Request Header

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

            

Request Parameters

• alias_value: Erforderlich. Der abzufragende Alias.
• platform: Optional. Wenn nicht angegeben, werden standardmäßig alle Plattformen verwendet.

Antwortbeispiel

Successful Response

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

            

Response Data

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

            

• Wenn ein Statistikelement nicht gefunden wird, ist es null; andernfalls ist es der Wert des Statistikelements.

Alias löschen

Löscht einen Alias und die Verknüpfungsbeziehung zwischen dem Alias und Geräten.

              
              DELETE /v4/aliases/{alias_value}

            

Anfragebeispiel

Request Header

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

            

Request Parameters

• alias_value: Erforderlich. Der zu löschende Alias.
• platform: Optional. Wenn nicht angegeben, werden standardmäßig alle Plattformen verwendet.

Antwortbeispiel

• Erfolg

              
              success

            

• Fehler

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

            

Online-Status des Benutzers abrufen

Endpoint

              
              POST /v4/devices/status/

            

Anfragebeispiel

Request Header

              
              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, deren Online-Status benötigt wird. Pro Abfrage werden bis zu 1 000 registration_id-Werte unterstützt.
• Diese API kann nur für einen AppKey aufgerufen werden, der für diese Funktion freigegeben wurde.

Antwortbeispiel

Successful Response

              
              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: Innerhalb der letzten 10 Minuten online.
  • false: Innerhalb der 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.
• Ungültige regid-Werte oder regid-Werte, die nicht zum AppKey gehören, bestehen die Validierung nicht.

API zur Abfrage von Tag-/Alias-Kontingentinformationen

Fragt Kontingentinformationen ab, die sich auf den angegebenen AppKey, die Plattform und den Tag beziehen. Es können nicht mehr als 1 000 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://pushapi-sgp.engagelab.com/v4/tags/quota-info?platform=android&tags=tag1&tags=tag2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YjA2MTBmZGE0M2JmNmFkMTczNGNjMWY2OmQyNGMzZDk1Yzk1M2M3YmFkNzRkM2Q5YQ=='

            

Successful Response

              
              {
  "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 Gerätekontingent für einen einzelnen Tag an.
• useUidQuota: Gibt die detaillierte Anzahl der an jeden Tag gebundenen Geräte an.

Failed Response

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

            

HTTP-Statuscodes

Referenzdokument: Http-Status-Code

Business-Rückgabecodes