API d'enregistrement des appareils

L'API d'enregistrement des appareils fournit des interfaces serveur pour enregistrer les tokens d'appareils et obtenir les registration_id dans AppPush.

Obtenir registration_id à l'aide d'un Token

Cette API permet à un serveur d'inscrire des utilisateurs AppPush à l'aide de FCM Tokens ou d'APNs Device Tokens et d'obtenir le registration_id généré par EngageLab. Une fois obtenu, le registration_id peut être utilisé pour cibler un utilisateur lors d'un push et avec les APIs liées aux appareils, telles que les tags et les alias.

Limites d'utilisation

• Chaque requête permet d'inscrire de 1 à 500 Tokens.
• Une requête ne peut contenir que les Tokens d'une seule plateforme : soit un lot de FCM Tokens, soit un lot d'APNs Device Tokens. Les Tokens FCM et APNs ne peuvent pas être mélangés dans une même requête.
• Les requêtes répétées avec la même application, la même plateforme et le même Token sont idempotentes. Aucun utilisateur en double n'est créé et le registration_id existant est renvoyé.
• Les résultats sont renvoyés dans le même ordre que les Tokens de la requête.

Endpoint

              
              POST /v4/devices/token/registration_id

            

L'URL complète de la requête se compose de la Base URL du centre de données de l'application et du chemin ci-dessus. Pour les adresses des centres de données et l'authentification, consultez la Présentation de REST API.

En-têtes de la requête

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

            

Paramètres de la requête

Règles de format des Tokens

• FCM Token : doit être une chaîne non vide de 400 caractères maximum. Seuls les caractères ASCII imprimables (0x21–0x7E) sont autorisés. Les espaces, retours à la ligne et espaces en début ou en fin de chaîne sont interdits.
• APNs Device Token : doit être une chaîne hexadécimale non vide, comportant un nombre pair de caractères et ne dépassant pas 400 caractères. Seuls 0-9, a-f et A-F sont autorisés. Les espaces, chevrons et autres séparateurs sont interdits.

Cette API valide uniquement le format du Token et ne peut pas confirmer si un Token est actuellement valide. Sa validité est déterminée par le résultat réel du push FCM ou APNs.

Exemple de requête Android (FCM)

              
              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"
    ]
  }'

            

Exemple de requête iOS (APNs)

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

            

Paramètres de réponse

Codes de résultat individuels :

Exemple de réponse réussie

Lors de la première inscription, is_new vaut 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
    }
  ]
}

            

Lorsqu'un Token déjà inscrit est envoyé à nouveau, le même registration_id est renvoyé et is_new vaut false :

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

            

Exemple d'échec pour un Token individuel

Si un Token d'un lot présente un format non valide ou si son inscription échoue, cet élément renvoie une erreur dans code et message, tandis que les autres Tokens peuvent être traités normalement. Dans l'exemple suivant, le Token vide échoue à la validation du format :

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

            

Exemple d'échec de la requête

Si les paramètres globaux de la requête ne sont pas valides, l'API renvoie HTTP 400. Par exemple, une requête iOS sans apns_production renvoie :

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

            

Erreurs de requête courantes :

• platform n'est ni android ni ios ;
• tokens est vide ou contient plus de 500 éléments ;
• une requête Android contient apns_production ;
• une requête iOS ne contient pas apns_production.

Réponses de l'API

Codes d'état HTTP

Consultez Code d'état HTTP.

Codes d'erreur

Le tableau suivant présente les codes d'erreur au niveau de la requête. Dans une requête par lot, l'erreur d'un Token individuel est renvoyée dans results[].code et results[].message et n'affecte pas le traitement des autres Tokens.