Tag Alias API

Die Geräte-API dient dazu, Tag- und Alias-Informationen eines Geräts serverseitig abzufragen, zu setzen, zu aktualisieren und zu löschen. Stellen Sie sicher, dass serverseitig gesetzte Tags nicht vom Client überschrieben werden.

• Wenn Sie mit Tags nicht vertraut sind, empfiehlt es sich, entweder die Logik von Tag oder Alias zu verwenden – jedoch nicht beide gleichzeitig und nicht gemischt zwischen Client- und Serverseite.
• Falls Sie beide verwenden, achten Sie darauf, dass Ihre Anwendung die Synchronisierung von Tags und Aliases zuverlässig handhabt.

Weitere Informationen zu Tag und Alias finden Sie in der API-Dokumentation der jeweiligen Client-Plattform:

• Android – Tag und Alias
• iOS – Tag und Alias
• HarmonyOS – Tag und Alias

Regeln und Einschränkungen für die Verwendung von Tags

• Maximal 100.000 Tags pro AppKey
• Maximale Tag-Länge: 40 Byte; zulässige Zeichen sind Buchstaben (Groß- und Kleinschreibung wird unterschieden), Zahlen, Unterstriche und chinesische Schriftzeichen.
• Maximal 100 Tags pro Gerät
• Maximal 100.000 Geräte pro Tag

Wenn Sie Abonnent:in eines kostenpflichtigen Tarifs sind und das Nutzungslimit Ihres AppKeys anpassen möchten, Vertrieb kontaktieren: Sales@engagelab.com

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

• Alias-Zuordnung: Ein Alias kann nur einem Gerät zugewiesen werden, ebenso kann jedes Gerät innerhalb eines AppKeys nur mit einem Alias verknüpft werden.
• Maximale Alias-Länge: 40 Byte; zulässige Zeichen sind Buchstaben (Groß- und Kleinschreibung wird unterschieden), Zahlen, Unterstriche und chinesische Schriftzeichen.

Wenn Sie Abonnent:in eines kostenpflichtigen Tarifs sind und das Nutzungslimit Ihres AppKeys anpassen möchten, Vertrieb kontaktieren: Sales@engagelab.com

API-Übersicht

Die Geräte-API ermöglicht das serverseitige Abfragen, Setzen, Aktualisieren und Löschen von Tag- und Alias-Informationen eines Geräts.

Es stehen drei API-Endpunkte zur Verfügung: Gerät, Tag, Alias:

• Gerät: Abfrage/Setzen verschiedener Geräteeigenschaften, einschließlich Tags und Alias
• Tag: Abfrage/Setzen/Löschen von Tags eines Geräts
• Alias: Abfrage/Setzen/Löschen des Alias eines Geräts

Hinweis zur registration_id:
Die registration_id eines Geräts wird nach der Integration auf der Client-Seite ermittelt. Weitere Details finden Sie in der API-Dokumentation für Android, iOS und HarmonyOS.

Serverseitig gibt es keine Möglichkeit, die registration_id eines Geräts zu erhalten. Entwickler:innen müssen die registration_id auf der Client-Seite abfragen und auf dem eigenen Server speichern.

Aufrufadresse

https://pushapi-sgp.engagelab.com/v4/devices

Abfrage der Anzahl von Tags unter einem AppKey

Ziel-URL

              
              GET /v4/tags_count

            

Beispielanfrage

Anfrage-Header

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

            

Beispiel

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

            

Anfrageparameter

• tags: Abzufragende Tag-Strings, Pflichtfeld, maximal 1.000 Tags pro Abfrage (tags=tag1&tags=tag2&tags=tag3)
• platform: Abzufragende Plattform, Pflichtfeld, zulässige Werte: android, ios, hmos. Andere Werte sind nicht erlaubt.

Beispielantwort

• Eine erfolgreiche Antwort liefert ein JSON-Objekt mit dem Feld tagsCount. Dies ist eine Sammlung von Schlüssel-Wert-Paaren, wobei der Schlüssel der Tag-Name und der Wert die Anzahl dieses Tags ist.
• Bei Fehlern wird ein JSON-Objekt mit Fehlerinformationen zurückgegeben. Das Feld code gibt den Fehlercode an, das Feld message die Fehlermeldung.

Erfolgreiche Rückgabe

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

            

Fehlgeschlagene Rückgabe

              
              {
    "error": {
        "code": 21008,
        "message": "app_key ist keine 24-stellige Zeichenkette oder existiert nicht"
    }
}

            

Abfrage von Alias und Tags eines Geräts

Ruft alle Attribute des aktuellen Geräts ab, einschließlich Tags und Alias.

Aufrufadresse

              
              GET /v4/devices/{registration_id}

            

Beispielanfrage

Anfrage-Header

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

            

Anfrageparameter

• Keine

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

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

            

• Wird keine Statistik gefunden, ist der Wert null, andernfalls wird der Wert zurückgegeben.

Setzen von Alias und Tags eines Geräts

Aktualisiert die angegebenen Attribute des aktuellen Geräts, derzeit werden Tags und Alias unterstützt.

Aufrufadresse

              
              POST /v4/devices/{registration_id}

            

Beispielanfrage

Anfrage-Header

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

            

Anfragedaten

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

            

Anfrageparameter

• tags: Unterstützt „add“, „remove“ oder einen leeren String. Ist das tags-Attribut ein leerer String, werden alle Tags gelöscht; unter add/remove werden die angegebenen Tags hinzugefügt oder entfernt.
• alias: Aktualisiert das Alias-Attribut des Geräts; ist alias ein leerer String, wird der Alias des angegebenen Geräts gelöscht.

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

              
              success

            

Fehlgeschlagene Rückgabe

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

            

Löschen eines Geräts

Löscht das Gerät.

Aufrufadresse

              
              DELETE /v4/devices/{registration_id}

            

Beispielanfrage

Anfrage-Header

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

            

Anfragedaten

• Keine

Anfrageparameter

• Keine

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

              
              success

            

Fehlgeschlagene Rückgabe

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

            

Abfrage der Tag-Liste

Ruft eine Liste aller Tags der aktuellen Anwendung ab.

Aufrufadresse

              
              GET /v4/tags/

            

Beispielanfrage

Anfrage-Header

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

            

Anfrageparameter

• Keine

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

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

            

• Ist keine Statistik vorhanden, ist der Wert null, andernfalls wird der Wert zurückgegeben.

Abfrage der Bindung zwischen Gerät und Tag

Prüft, ob ein Gerät unter einem bestimmten Tag geführt wird.

Aufrufadresse

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

            

Beispielanfrage

Anfrage-Header

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

            

Anfrageparameter

• registration_id (erforderlich): Die registration_id des Geräts

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

              
              {"result": true/false}

            

Tags aktualisieren

Geräte zu einem Tag hinzufügen oder entfernen.

Aufrufadresse

              
              POST /v4/tags/{tag_value}

            

Beispielanfrage

Anfrage-Header

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

            

Anfragedaten

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

            

Anfrageparameter

• action: Aktionstyp, zwei Optionen: „add“ oder „remove“, gibt an, ob hinzugefügt oder entfernt wird.
• registration_ids: Die registration_id der hinzuzufügenden/zu entfernenden Geräte.
• add/remove: Unterstützt jeweils bis zu 1.000 Geräte.

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

              
              success

            

Fehlgeschlagene Rückgabe

              
              {
    "error": {
        "code": 27005,
        "message": "registration id ist ungültig",
        "data": "{\"invalid_regids\":[\"18071adc021ff8df80\",\"100d85592955c1f1058\"]}"
    }
}

            

Tag löschen

Löscht einen Tag und die Verknüpfung zwischen Tag und Gerät.

Aufrufadresse

              
              DELETE /v4/tags/{tag_value}

            

Beispielanfrage

Anfrage-Header

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

            

Anfrageparameter

• platform ist ein optionaler Parameter; wird er nicht angegeben, gilt dies für alle Plattformen.

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

              
              success

            

Fehlgeschlagene Rückgabe

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

            

Abfrage von Alias (Bindung mit Geräten)

Ruft die Geräte unter dem angegebenen Alias ab.

Aufrufadresse

              
              GET /v4/aliases/{alias_value}

            

Beispielanfrage

Anfrage-Header

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

            

Anfrageparameter

• platform ist ein optionaler Parameter; wird er nicht angegeben, gilt dies für alle Plattformen.

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

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

            

• Ist keine Statistik vorhanden, ist der Wert null, andernfalls wird der Wert zurückgegeben.

Alias löschen

Löscht einen Alias und die Bindung zwischen Alias und Gerät.

Aufrufadresse

              
              DELETE /v4/aliases/{alias_value}

            

Beispielanfrage

Anfrage-Header

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

            

Anfrageparameter

• platform ist ein optionaler Parameter; wird er nicht angegeben, gilt dies für alle Plattformen.

Beispielantwort

• Erfolg

              
              success

            

• Fehler

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

            

Online-Status von Nutzer:innen abfragen

Aufrufadresse

              
              POST /v4/devices/status/

            

Beispielanfrage

Anfrage-Header

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

            

Anfragedaten

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

            

Anfrageparameter

• registration_ids: Die registration_id der Nutzer:innen, deren Online-Status abgefragt werden soll. Es können bis zu 1.000 registration_ids abgefragt werden.
• Sie benötigen einen AppKey, für den dieser Dienst aktiviert wurde, um diese API nutzen zu können.

Beispielantwort

Erfolgreiche Rückgabe

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

            

Rückgabedaten

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

            

Feldbeschreibung:

• online
  • true: Innerhalb der letzten 10 Minuten online.
  • false: Seit mehr als 10 Minuten nicht online.
• last_online_time
  • Wenn online true ist, wird dieses Feld nicht zurückgegeben.
  • Fehlt das Feld bei false, war die letzte Online-Zeit vor mehr als zwei Tagen.
• Bei ungültiger regid oder regid, die nicht zum AppKey gehört, schlägt die Verifizierung fehl.

Abfrage der Tag/Alias-Quota-Informationen

Abfrage der Quota-Informationen für den angegebenen AppKey, die Plattform und die Tags. Pro Abfrage können maximal 1.000 Tags angegeben werden.

Aufrufadresse

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

            

Beispielanfrage

              
              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=='

            

Erfolgreiche Rückgabe

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

            

Feldbeschreibung:

• totalTagQuota: Gesamtanzahl der Tags unter der Anwendung
• useTagQuota: Verwendete Tag-Quota
• totalAliasQuota: Gesamtanzahl der Aliases unter der Anwendung
• useAliasQuota: Verwendete Alias-Quota
• tagUidQuota: Quota für die Anzahl der Geräte pro Tag
• useUidQuota: Details zur Anzahl der an jeden Tag gebundenen Geräte

Fehlgeschlagene Rückgabe

              
              {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}

            

HTTP-Statuscodes

Referenzdokument: HTTP-Status-Code

Geschäftliche Rückgabecodes

Stichworte: Geräteverwaltung, Tag-Management, Alias-Management, API-Schnittstelle

CTA: Vertrieb kontaktieren

Hinweis:
Alle Angaben entsprechen den aktuellen Dokumentationsstandards für eine professionelle, deutschsprachige Entwickler:innen-Zielgruppe.