API Tag et Alias

L’API Device est utilisée pour interroger, définir, mettre à jour et supprimer les informations de tag et d’alias d’un appareil côté serveur. Lors de son utilisation, veillez à éviter que les tags définis côté serveur ne soient écrasés par le côté client.

• Si vous n’êtes pas familier avec la logique des tags et des alias, il est recommandé de n’utiliser qu’un seul côté : soit le côté client, soit le côté serveur.
• Si les deux côtés sont utilisés en même temps, assurez-vous que votre application peut gérer correctement la synchronisation des tags et des alias.

Pour des informations détaillées sur les tags et les alias, veuillez consulter la documentation de l’API de la plateforme cliente correspondante.

• web - tag, alias

Contraintes et règles d’utilisation des TAG

• Limite du nombre de TAG : sous une même appkey, vous pouvez créer jusqu’à 100 000 tags.
• Limite de longueur des TAG : la longueur maximale de chaque tag est de 40 octets. Les caractères valides incluent les lettres (sensibles à la casse), les chiffres, les tirets bas et les caractères chinois.
• Limite de liaison des TAG d’appareil : chaque appareil peut être associé à un maximum de 100 tags.
• Limite du nombre d’appareils : sous un même tag, vous pouvez ajouter jusqu’à 100 000 appareils.

Si vous disposez d’un forfait payant et souhaitez ajuster les limites d’utilisation d’une AppKey payante, veuillez contacter notre équipe commerciale à l’adresse Sales@engagelab.com.

Contraintes et règles d’utilisation des alias

• Relation de correspondance entre appareil et alias : un alias ne peut correspondre qu’à un seul appareil et ne peut pas correspondre à plusieurs appareils. De même, chaque appareil ne peut être associé qu’à un seul alias dans le périmètre de l’appkey et ne peut pas être associé à plusieurs alias.
• Limite du nombre d’alias : sous une même appkey, vous pouvez créer jusqu’à 100 000 aliases.
• Limite de longueur des alias : la longueur maximale de chaque alias est de 40 octets. Les caractères valides incluent les lettres (sensibles à la casse), les chiffres, les tirets bas et les caractères chinois.

Si vous disposez d’un forfait payant et souhaitez ajuster les limites d’utilisation d’une AppKey payante, veuillez contacter notre équipe commerciale à l’adresse Sales@engagelab.com.

Vue d’ensemble de l’API

L’API Device est utilisée pour interroger, définir, mettre à jour et supprimer les informations de tag et d’alias d’un appareil côté serveur.

Elle comprend trois groupes d’API : device, tag et alias. Parmi eux :

• device est utilisé pour interroger/définir diverses propriétés d’un appareil, y compris les tags et l’alias ;
• tag est utilisé pour interroger/définir/supprimer les tags d’appareil ;
• alias est utilisé pour interroger/définir/supprimer les alias d’appareil.

Une autre information clé dont vous avez besoin est le registration ID :

Le registration_id de l’appareil est obtenu après l’intégration côté client. Pour plus de détails, consultez la documentation de l’API Web.

Le côté serveur ne fournit pas d’API pour obtenir la valeur registration_id de l’appareil. Les développeurs doivent obtenir le registration ID depuis le côté client et le téléverser vers le serveur du développeur pour le stocker.

Interroger le nombre de tags sous une AppKey

Endpoint

              
              GET /v4/tags_count

            

Exemple de requête

En-têtes de requête

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

            

Exemple de requête

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

            

Paramètres de requête

• tags : interroge les chaînes de tag spécifiées. Obligatoire. Jusqu’à 1 000 tags peuvent être interrogés dans une seule requête (tags=tag1&tags=tag2&tags=tag3).
• platform : interroge la plateforme spécifiée. Obligatoire. Les valeurs valides sont android, ios, hmos et web. Les autres valeurs ne sont pas autorisées.

Exemple de réponse

• Une réponse réussie renvoie un objet JSON contenant un champ tagsCount, qui est une collection de paires clé-valeur où la clé est le nom du tag et la valeur est le nombre associé à ce tag.
• Si la requête échoue, un objet JSON contenant des informations d’erreur est renvoyé. Le champ code indique le code d’erreur, et le champ message indique le message d’erreur.

Réponse réussie

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

            

Réponse en échec

              
              {
  "error": {
    "code": 21008,
    "message": "app_key is not a 24 size string or does not exist"
  }
}

            

Interroger l’alias et les tags d’un appareil

• Obtient toutes les propriétés de l’appareil actuel, y compris les tags et l’alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Exemple de requête

En-têtes de requête

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

            

Paramètres de requête

• registration_id : obligatoire. Le registration_id de l’appareil.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

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

            

• Si l’élément statistique est introuvable, sa valeur est null ; sinon, il s’agit de la valeur de l’élément statistique.

Définir l’alias et les tags d’un appareil

• Met à jour les propriétés spécifiées de l’appareil actuel. Prend actuellement en charge les tags et l’alias.

Endpoint

              
              POST /v4/devices/{registration_id}

            

Exemple de requête

En-têtes de requête

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

            

Données de requête

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

            

Paramètres de requête

• registration_id : obligatoire. Le registration_id de l’appareil.
• tags : prend en charge add, remove ou une chaîne vide. Lorsque le paramètre tags est une chaîne vide, cela signifie que tous les tags seront effacés. add/remove est utilisé pour ajouter ou supprimer les tags spécifiés.
• alias : met à jour la propriété alias de l’appareil. Lorsque l’alias est une chaîne vide, l’alias de l’appareil spécifié est supprimé.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

              
              success

            

Réponse en échec

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

            

Interroger la liste des tags

• Obtient la liste de tous les tags dans l’application actuelle.

Endpoint

              
              GET /v4/tags/

            

Exemple de requête

En-têtes de requête

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

            

Paramètres de requête

• Aucun

Exemple de réponse

Réponse réussie

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

            

Données de réponse

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

            

• Si l’élément statistique est introuvable, sa valeur est null ; sinon, il s’agit de la valeur de l’élément statistique.

Interroger la relation de liaison entre un appareil et un tag

• Vérifie si un appareil appartient à un tag.

Endpoint

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

            

Exemple de requête

En-têtes de requête

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

            

Paramètres de requête

• tag_value : obligatoire. Le tag à interroger.
• registration_id : obligatoire. Le registration_id de l’appareil.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

              
              {"result": true}

            

Mettre à jour un tag

• Ajoute ou supprime des appareils pour un tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Exemple de requête

En-têtes de requête

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

            

Données de requête

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

            

Paramètres de requête

• tag_value : obligatoire. Le tag à interroger.
• action : type d’opération, avec deux options : "add" et "remove", indiquant si cette requête vise à ajouter ou à supprimer.
• registration_ids : les valeurs registration_id des appareils à ajouter ou à supprimer.
• add/remove : prend en charge jusqu’à 1 000 éléments chacun.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

              
              success

            

Réponse en échec

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

            

Supprimer un tag

Supprime un tag et l’association entre le tag et les appareils.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Exemple de requête

En-têtes de requête

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

            

Paramètres de requête

• tag_value : obligatoire. Le tag à interroger.
• platform : facultatif. S’il est omis, la valeur par défaut est toutes les plateformes.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

              
              success

            

Réponse en échec

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

            

Interroger un alias (relation de liaison avec un appareil)

              
              GET /v4/aliases/{alias_value}
Get the device under the specified alias.

            

Interroger un alias

• Obtient l’appareil associé à l’alias spécifié.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Exemple de requête

En-têtes de requête

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

            

Paramètres de requête

• alias_value : obligatoire. L’alias à interroger.
• platform : facultatif. S’il est omis, la valeur par défaut est toutes les plateformes.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

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

            

• Si l’élément statistique est introuvable, sa valeur est null ; sinon, il s’agit de la valeur de l’élément statistique.

Supprimer un alias

Supprime un alias et la relation de liaison entre l’alias et les appareils.

              
              DELETE /v4/aliases/{alias_value}

            

Exemple de requête

En-têtes de requête

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

            

Paramètres de requête

• alias_value : obligatoire. L’alias à supprimer.
• platform : facultatif. S’il est omis, la valeur par défaut est toutes les plateformes.

Exemple de réponse

• Succès

              
              success

            

• Échec

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

            

Obtenir le statut en ligne de l’utilisateur

Endpoint

              
              POST /v4/devices/status/

            

Exemple de requête

En-têtes de requête

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

            

Données de requête

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

            

Paramètres de requête

• registration_ids : les valeurs registration_id des utilisateurs pour lesquels le statut en ligne est requis. Jusqu’à 1 000 valeurs registration_id sont prises en charge par requête.
• Cette API ne peut être appelée que pour les AppKeys ayant demandé et activé ce service.

Exemple de réponse

Réponse réussie

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

            

Données de réponse

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

            

Données de réponse

• online
  • true : en ligne au cours des 10 dernières minutes
  • false : pas en ligne au cours des 10 dernières minutes
• last_online_time
  • lorsque online est true, ce champ n’est pas renvoyé
  • lorsque online est false et que ce champ n’est pas renvoyé, cela signifie que la dernière connexion remonte à plus de deux jours
• Pour les valeurs regid invalides ou les valeurs regid qui n’appartiennent pas à l’appkey, la validation échouera.

API de requête des informations de quota TAG/alias

Interroge les informations de quota pertinentes pour l’AppKey, la plateforme et le tag spécifiés. Il n’est pas possible d’interroger plus de 1 000 tags à la fois.

Endpoint

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

            

Exemple de requête

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

            

Réponse réussie

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

            

Descriptions des champs de réponse :

• totalTagQuota : indique le quota total du nombre de tags dans l’application.
• useTagQuota : indique le quota de tags utilisé.
• totalAliasQuota : indique le quota total du nombre d’aliases dans l’application.
• useAliasQuota : indique le quota d’aliases utilisé.
• tagUidQuota : indique le quota du nombre d’appareils sous un seul tag.
• useUidQuota : indique le nombre détaillé d’appareils liés à chaque tag.

Réponse en échec

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

            

Codes de statut HTTP

Document de référence : Http-Status-Code

Codes de réponse métier