Tag Alias API

Die Device API ermöglicht das Abfragen, Setzen, Aktualisieren und Löschen von Geräte-Tags und Alias-Informationen auf der Server-Seite. Dabei ist zu beachten, dass vom Server gesetzte Tags nicht durch die Client-Seite überschrieben werden dürfen.

• Wenn Sie mit Tags nicht vertraut sind, empfiehlt es sich, die Alias-Logik ausschließlich auf der Client- oder Server-Seite zu verwenden.
• Falls Sie beide Seiten gleichzeitig nutzen, stellen Sie bitte sicher, dass Ihre Anwendung die Synchronisierung von Tags und Aliases korrekt handhaben kann.

Weitere Informationen zu Tags und Aliases finden Sie in der API-Dokumentation Ihrer jeweiligen Client-Plattform.

• web-tag,alias

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

• Tag-Anzahl-Limit: Unter einem einzelnen AppKey können bis zu 100.000 Tags erstellt werden.
• Tag-Längen-Limit: Die maximale Länge eines Tags beträgt 40 Byte. Erlaubt sind Buchstaben (Groß- und Kleinschreibung wird unterschieden), Zahlen, Unterstriche und chinesische Schriftzeichen.
• Tag-Bindungslimit pro Gerät: Pro Gerät sind maximal 100 Tag-Verknüpfungen möglich.
• Geräteanzahl-Limit pro Tag: Unter einem einzelnen Tag können bis zu 100.000 Geräte hinzugefügt werden.

Wenn Sie Abonnent unseres kostenpflichtigen Plans sind und das Nutzungslimit Ihres AppKeys anpassen möchten, wenden Sie sich bitte an unser Vertriebsteam: Sales@engagelab.com

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

• Gerät-zu-Alias-Zuordnung: Ein Alias kann nur einem Gerät zugeordnet werden, nicht mehreren. Ebenso kann jedes Gerät innerhalb eines AppKeys nur einem Alias zugeordnet werden, nicht mehreren.
• Alias-Anzahl-Limit: Unter einem einzelnen AppKey können bis zu 100.000 Aliases erstellt werden.
• Alias-Längen-Limit: Die maximale Länge eines Alias beträgt 40 Byte. Erlaubt sind Buchstaben (Groß- und Kleinschreibung wird unterschieden), Zahlen, Unterstriche und chinesische Schriftzeichen.

Wenn Sie Abonnent unseres kostenpflichtigen Plans sind und das Nutzungslimit Ihres AppKeys anpassen möchten, wenden Sie sich bitte an unser Vertriebsteam: Sales@engagelab.com

API-Übersicht

Die Device API ermöglicht das Abfragen, Setzen, Aktualisieren und Löschen von Geräte-Tags und Alias-Informationen auf der Server-Seite.

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

• device: Zum Abfragen/Setzen verschiedener Geräteeigenschaften, einschließlich Tags und Alias.
• tag: Zum Abfragen/Setzen/Löschen von Tags eines Geräts.
• alias: Zum Abfragen/Setzen/Löschen von Geräte-Alias.

Wichtige Information: Die Registrierung-ID (registration_id) wird benötigt.

Die registration_id eines Geräts wird nach der Integration auf der Client-Seite erhalten. Details finden Sie in der API-Dokumentation für das Web.

Der Server stellt keine API zur Verfügung, um die registration_id eines Geräts abzurufen. Entwickler:innen müssen die registration_id vom Client beziehen und auf dem eigenen Server speichern.

Anzahl von Tags unter einem AppKey abfragen

Aufrufadresse

              
              GET /v4/tags_count

            

Beispielanfrage

Request-Header

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

            

Beispielaufruf

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

            

Request-Parameter

• tags: Abfrage der angegebenen Tag-Strings, Pflichtfeld, es können maximal 1.000 Tags gleichzeitig abgefragt werden (tags=tag1&tags=tag2&tags=tag3)
• platform: Abfrage der angegebenen Plattform, Pflichtfeld, zulässige Werte: android, ios; andere Werte sind nicht erlaubt.

Beispielantwort

• Eine erfolgreiche Antwort gibt ein JSON-Objekt mit dem Feld tagsCount zurück. Dies ist eine Key-Value-Sammlung, wobei der Key der Tag-Name und der Value 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 Antwort

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

            

Fehlerhafte Antwort

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

            

Geräte-Alias und -Tags abfragen

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

Aufrufadresse

              
              GET /v4/devices/{registration_id}

            

Beispielanfrage

Request-Header

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

            

Request-Parameter

• Keine

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

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

            

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

Alias und Tags eines Geräts setzen

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

Aufrufadresse

              
              POST /v4/devices/{registration_id}

            

Beispielanfrage

Request-Header

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

            

Request-Daten

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

            

Request-Parameter

• tags: Unterstützt add, remove oder leere Zeichenkette. Ist der tags-Parameter eine leere Zeichenkette, werden alle Tags entfernt; unter add/remove werden die angegebenen Tags hinzugefügt oder entfernt.
• alias: Aktualisiert das Alias-Attribut des Geräts; ist alias eine leere Zeichenkette, wird das Alias des angegebenen Geräts gelöscht.

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

              
              success

            

Fehlerhafte Antwort

              
              {
  "error":{
    "code":27002, 
    "message":"unbekannter Fehler"
    }
}

            

Gerät löschen

• Löscht das Gerät.

Aufrufadresse

              
              DELETE /v4/devices/{registration_id}

            

Beispielanfrage

Request-Header

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

            

Request-Daten

• Keine

Request-Parameter

• Keine

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

              
              success

            

Fehlerhafte Antwort

              
              {
  "error":{
    "code":27002, 
    "message":"unbekannter Fehler"
    }
}

            

Tag-Liste abfragen

• Ruft eine Liste aller Tags der aktuellen Anwendung ab.

Aufrufadresse

              
              GET /v4/tags/

            

Beispielanfrage

Request-Header

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

            

Request-Parameter

• Keine

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

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

            

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

Bindung zwischen Gerät und Tag abfragen

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

Aufrufadresse

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

            

Beispielanfrage

Request-Header

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

            

Request-Parameter

• registration_id (Pflichtfeld): Registrierung-ID des Geräts

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

              
              {"result": true/false}

            

Tags aktualisieren

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

Aufrufadresse

              
              POST /v4/tags/{tag_value}

            

Beispielanfrage

Request-Header

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

            

Request-Daten

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

            

Request-Parameter

• action: Aktionstyp, zwei Optionen: "add", "remove", gibt an, ob Geräte hinzugefügt oder entfernt werden.
• registration_ids: Die Registrierung-IDs der hinzuzufügenden/zu entfernenden Geräte.
• add/remove: Unterstützt jeweils bis zu 1.000 Geräte.

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

              
              success

            

Fehlerhafte Antwort

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

            

Tag löschen

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

Aufrufadresse

              
              DELETE /v4/tags/{tag_value}

            

Beispielanfrage

Request-Header

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

            

Request-Parameter

• platform: Optional, wenn nicht angegeben, gilt die Aktion für alle Plattformen.

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten success

Fehlerhafte Antwort

              
              {
  "error":{
    "code":27002, 
    "message":"unbekannter Fehler"
    }
}

            

Alias abfragen (Bindung zu Geräten)

• Ruft die Geräte ab, die unter dem angegebenen Alias geführt werden.

Aufrufadresse

              
              GET /v4/aliases/{alias_value}

            

Beispielanfrage

Request-Header

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

            

Request-Parameter

• platform: Optional, wenn nicht angegeben, gilt die Aktion für alle Plattformen.

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

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

            

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

Alias löschen

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

Aufrufadresse

              
              DELETE /v4/aliases/{alias_value}

            

Beispielanfrage

Request-Header

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

            

Request-Parameter

• platform: Optional, wenn nicht angegeben, gilt die Aktion für alle Plattformen.

Beispielantwort

• Erfolg

              
                 success

            

• Fehler

              
              {
  "error":{
    "code":27002, 
    "message":"unbekannter Fehler"
    }
}

            

Online-Status von Nutzer:innen abfragen

Aufrufadresse

              
              POST /v4/devices/status/

            

Beispielanfrage

Request-Header

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

            

Request-Daten

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

            

Request-Parameter

• registration_ids: Registrierung-IDs der Nutzer:innen, für die der Online-Status abgefragt werden soll. Es können bis zu 1.000 IDs abgefragt werden.
• Für die Nutzung dieser API muss ein AppKey mit aktiviertem Service beantragt werden.

Beispielantwort

Erfolgreiche Antwort

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

            

Antwortdaten

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

            

Antwortfelder

• online
  • true: Nutzer:in ist seit maximal 10 Minuten online;
  • false: Nutzer:in ist seit mehr als 10 Minuten nicht online;
• last_online_time
  • Wenn online true ist, wird dieses Feld nicht zurückgegeben.
  • Wenn online false ist und das Feld fehlt, war der letzte Online-Zeitpunkt vor mehr als zwei Tagen;
• Bei ungültiger regid oder regid, die nicht zum AppKey gehört, schlägt die Überprüfung fehl.

Schnittstelle zur Abfrage von Tag/Alias-Kontingenten

Abfrage von 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://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
            }
        ]
    }
}

            

Feldbeschreibung:

• totalTagQuota: Gesamtanzahl der Tags, die in der Anwendung zulässig sind.
• useTagQuota: Anzahl der bereits verwendeten Tags.
• totalAliasQuota: Gesamtanzahl der zulässigen Aliases in der Anwendung.
• useAliasQuota: Anzahl der bereits verwendeten Aliases.
• tagUidQuota: Kontingent für die Anzahl der Geräte pro Tag.
• useUidQuota: Details zur Anzahl der an jeden Tag gebundenen Geräte.

Fehlerhafte Antwort

              
              {
    "error": {
        "code": 27002,
        "message": "Ungültiger Parameter"
    }
}

            

HTTP-Statuscodes

Referenzdokument: Http-Status-Code

Geschäftsspezifische Rückgabecodes