API Tag Alias

L'API Device est utilisée côté serveur pour interroger, définir, mettre à jour et supprimer les informations de tag et d'alias des appareils. Lors de son utilisation, veillez à ne pas laisser les tags définis par le serveur être écrasés par le client.

• Si vous n'êtes pas familiarisé avec la logique des tags et des alias, il est recommandé d'utiliser uniquement le côté client ou uniquement 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.

• Android - tag, alias
• iOS - tag, alias
• HarmonyOS - tag, alias

Limites et règles d'utilisation des TAG

• Limite du nombre de TAG : Sous un 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 underscores et les caractères chinois.
• Limite de liaison des TAG par appareil : Chaque appareil peut être lié à un maximum de 100 tags.
• Limite du nombre d'appareils : Sous un même tag, vous pouvez ajouter jusqu'à 100 000 appareils.

Si vous êtes un utilisateur d'une offre payante et souhaitez ajuster les limites d'utilisation de votre AppKey payante, veuillez contacter notre équipe commerciale à l'adresse Sales@engagelab.com.

Limites et règles d'utilisation des alias

• Correspondance entre appareil et alias : Un alias ne peut correspondre qu'à un seul appareil et ne peut pas correspondre à plusieurs appareils. De même, dans le périmètre d'un AppKey, chaque appareil ne peut être associé qu'à un seul alias et ne peut pas être associé à plusieurs alias.
• 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 underscores et les caractères chinois.

Si vous êtes un utilisateur d'une offre payante et souhaitez ajuster les limites d'utilisation de votre AppKey payante, veuillez contacter notre équipe commerciale à l'adresse Sales@engagelab.com.

Vue d'ensemble de l'API

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

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

• device est utilisé pour interroger/définir divers attributs de l'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é requise 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 pour Android, iOS et HarmonyOS.

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 côté client et le téléverser vers le serveur du développeur pour stockage.

Interroger le nombre de tags sous un AppKey

Endpoint

              
              GET /v4/tags_count

            

Exemple de requête

En-tête 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 tags spécifiées. Obligatoire. Jusqu'à 1 000 tags peuvent être interrogés à la fois (tags=tag1&tags=tag2&tags=tag3).
• platform : interroge la plateforme spécifiée. Obligatoire. Les valeurs valides sont android, ios et hmos. 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 sous 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

• Obtenez tous les attributs de l'appareil actuel, y compris les tags et l'alias.

Endpoint

              
              GET /v4/devices/{registration_id}

            

Exemple de requête

En-tête 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 un élément statistique n'est pas trouvé, 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

• Mettez à jour les attributs spécifiés 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ête 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, tous les tags sont effacés. add/remove signifie ajouter ou supprimer les tags spécifiés.
• alias : met à jour l'attribut d'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

• Obtenez la liste de tous les tags de l'application actuelle.

Endpoint

              
              GET /v4/tags/

            

Exemple de requête

En-tête de requête

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

            

Paramètres de requête

• Aucun

Exemple de requête

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 un élément statistique n'est pas trouvé, 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

• Interrogez si un appareil se trouve sous un tag.

Endpoint

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

            

Exemple de requête

En-tête 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

• Ajouter ou supprimer des appareils pour un tag.

Endpoint

              
              POST /v4/tags/{tag_value}

            

Exemple de requête

En-tête 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 ajoute ou supprime des appareils.
• registration_ids : les valeurs registration_id des appareils à ajouter ou supprimer.
• add/remove : prend en charge jusqu'à 1 000 entrées 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

Supprimez un tag et l'association entre le tag et les appareils.

Endpoint

              
              DELETE /v4/tags/{tag_value}

            

Exemple de requête

En-tête de requête

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

            

Paramètres de requête

• tag_value : obligatoire. Le tag à interroger.
• platform : facultatif. S'il n'est pas spécifié, toutes les plateformes sont utilisées par défaut.

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 les appareils)

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

            

Interroger un alias

• Obtenez les appareils sous l'alias spécifié.

Endpoint

              
              GET /v4/aliases/{alias_value}

            

Exemple de requête

En-tête de requête

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

            

Paramètres de requête

• alias_value : obligatoire. L'alias à interroger.
• platform : facultatif. S'il n'est pas spécifié, toutes les plateformes sont utilisées par défaut.

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 un élément statistique n'est pas trouvé, sa valeur est null ; sinon, il s'agit de la valeur de l'élément statistique.

Supprimer un alias

Supprimez un alias et la relation de liaison entre l'alias et les appareils.

              
              DELETE /v4/aliases/{alias_value}

            

Exemple de requête

En-tête de requête

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

            

Paramètres de requête

• alias_value : obligatoire. L'alias à supprimer.
• platform : facultatif. S'il n'est pas spécifié, toutes les plateformes sont utilisées par défaut.

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ête 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 dont 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 un AppKey ayant été approuvé pour cette fonctionnalité.

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 : hors 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.
• Les valeurs regid invalides ou les valeurs regid qui n'appartiennent pas à l'AppKey échoueront à la validation.

API de requête d'informations de quota TAG/Alias

Interrogez les informations de quota liées à l'AppKey, à la plateforme et au 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://pushapi-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 sous l'application.
• useTagQuota : indique le quota de tags utilisé.
• totalAliasQuota : indique le quota total du nombre d'alias sous l'application.
• useAliasQuota : indique le quota d'alias utilisé.
• tagUidQuota : indique le quota d'appareils pour 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 retour métier