Geräteregistrierungs-API

Die Geräteregistrierungs-API stellt serverseitige Schnittstellen zur Registrierung von Geräte-Token und zum Abrufen der registration_id in AppPush bereit.

registration_id über einen Token abrufen

Mit dieser API kann ein Server AppPush-Benutzer über FCM-Tokens oder APNs Device Tokens registrieren und die von EngageLab erzeugte registration_id abrufen. Anschließend kann die registration_id für gezielte Benutzer-Pushs sowie gerätebezogene APIs wie Tags und Aliase verwendet werden.

Nutzungseinschränkungen

• Pro Anfrage können 1–500 Tokens registriert werden.
• Eine Anfrage darf nur Tokens einer Plattform enthalten: entweder FCM-Tokens oder APNs Device Tokens. FCM- und APNs-Tokens dürfen nicht in derselben Anfrage gemischt werden.
• Wiederholte Anfragen mit derselben Anwendung, Plattform und demselben Token sind idempotent. Es wird kein Benutzer doppelt angelegt, und die vorhandene registration_id wird zurückgegeben.
• Die Ergebnisse werden in derselben Reihenfolge wie die Tokens in der Anfrage zurückgegeben.

Endpunkt

              
              POST /v4/devices/token/registration_id

            

Die vollständige Anfrage-URL setzt sich aus der Base URL des Rechenzentrums der Anwendung und dem oben genannten Pfad zusammen. Informationen zu Rechenzentrumsadressen und Authentifizierung finden Sie unter REST-API-Übersicht.

Anfrageheader

              
              Content-Type: application/json
Accept: application/json
Authorization: Basic base64_auth_string

            

Anfrageparameter

Formatregeln für Tokens

• FCM-Token: Muss eine nicht leere Zeichenfolge mit höchstens 400 Zeichen sein. Zulässig sind ausschließlich druckbare ASCII-Zeichen (0x21–0x7E). Leerzeichen, Zeilenumbrüche sowie führende oder nachgestellte Leerzeichen sind nicht zulässig.
• APNs Device Token: Muss eine nicht leere hexadezimale Zeichenfolge mit gerader Zeichenanzahl und höchstens 400 Zeichen sein. Zulässig sind nur 0-9, a-f und A-F. Leerzeichen, spitze Klammern und andere Trennzeichen sind nicht zulässig.

Diese API prüft nur das Token-Format und kann nicht bestätigen, ob ein Token aktuell gültig ist. Die Gültigkeit ergibt sich aus dem tatsächlichen Push-Ergebnis von FCM oder APNs.

Android-(FCM-)Anfragebeispiel

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "android",
    "tokens": [
      "fcm_token_1",
      "fcm_token_2"
    ]
  }'

            

iOS-(APNs-)Anfragebeispiel

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "ios",
    "tokens": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ],
    "apns_production": true
  }'

            

Antwortparameter

Ergebniscodes für einzelne Tokens:

Beispiel für eine erfolgreiche Antwort

Bei der ersten Registrierung ist is_new gleich true:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": true,
      "code": 0
    },
    {
      "token": "fcm_token_2",
      "registration_id": "13065ffa4e1a6cc91c4",
      "is_new": true,
      "code": 0
    }
  ]
}

            

Wird ein bereits registrierter Token erneut übermittelt, wird dieselbe registration_id zurückgegeben und is_new ist false:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    }
  ]
}

            

Beispiel für einen fehlgeschlagenen einzelnen Token

Hat ein Token in einer Batch-Anfrage ein ungültiges Format oder schlägt seine Registrierung fehl, enthält dieses Element einen Fehler in code und message. Die übrigen Tokens können weiterhin normal verarbeitet werden. Im folgenden Beispiel schlägt die Formatprüfung des leeren Tokens fehl:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    },
    {
      "token": "",
      "is_new": false,
      "code": 21003,
      "message": "invalid fcm token format"
    }
  ]
}

            

Beispiel für eine fehlgeschlagene Anfrage

Sind die Anfrageparameter insgesamt ungültig, gibt die API HTTP 400 zurück. Fehlt beispielsweise bei einer iOS-Anfrage apns_production, lautet die Antwort:

              
              {
  "error": {
    "code": 21003,
    "message": "apns_production is required for ios"
  }
}

            

Häufige Anfragefehler:

• platform ist weder android noch ios;
• tokens ist leer oder enthält mehr als 500 Einträge;
• eine Android-Anfrage enthält apns_production;
• in einer iOS-Anfrage fehlt apns_production.

API-Antworten

HTTP-Statuscodes

Siehe HTTP-Statuscode.

Fehlercodes

Die folgende Tabelle enthält Fehlercodes auf Anfrageebene. In einer Batch-Anfrage werden Fehler einzelner Tokens über results[].code und results[].message zurückgegeben und beeinflussen die Verarbeitung der übrigen Tokens nicht.