API d'Alias de Tag

L'API Device est utilisée pour interroger, définir, mettre à jour et supprimer les informations de tag et d'alias de l'appareil côté serveur. Lors de son utilisation, veillez à ce que le tag défini côté serveur ne soit pas écrasé par le client.

• Si vous n'êtes pas familier avec les tags, il est recommandé de n'utiliser la logique d'alias que d'un seul côté, soit client, soit serveur.
• Si vous utilisez les deux, assurez-vous que votre application peut gérer la synchronisation des tags et des alias.

Pour plus d'informations sur les tags et alias, veuillez vous référer à la description de l'API de la plateforme client correspondante.

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

Règles et restrictions d'utilisation des TAG

• Limite du nombre de TAG : Sous un seul 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 (sensible à la casse), les chiffres, les underscores et les caractères chinois.
• Limite de liaison TAG par appareil : Chaque appareil peut lier jusqu'à 100 tags.
• Limite du nombre d'appareils : Sous un seul tag, vous pouvez ajouter jusqu'à 100 000 appareils.

Si vous êtes abonné à notre offre payante et souhaitez ajuster la limite d'utilisation de votre AppKey payant, veuillez contacter notre équipe commerciale à : Sales@engagelab.com

Règles et restrictions d'utilisation des alias

• Correspondance appareil-alias : Un alias ne peut correspondre qu'à un seul appareil, et non à plusieurs appareils. De même, chaque appareil dans la portée de l'appkey ne peut être associé qu'à un seul alias, et non à plusieurs alias.
• Limite de longueur des alias : La longueur maximale de chaque alias est de 40 octets. Les caractères valides incluent les lettres (sensible à la casse), les chiffres, les underscores et les caractères chinois.

Si vous êtes abonné à notre offre payante et souhaitez ajuster la limite d'utilisation de votre AppKey payant, veuillez contacter notre équipe commerciale à : Sales@engagelab.com

Présentation de l'API

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

Elle contient trois API : device, tag, alias :

• 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 le tag de l'appareil ;
• alias est utilisé pour interroger/définir/supprimer l'alias de l'appareil.

L'identifiant d'enregistrement est également une information clé à utiliser :

Le registration_id de l'appareil est obtenu après l'intégration côté client, voir la documentation API pour Android, iOS et HarmonyOS pour plus de détails ;

Le côté serveur ne fournit pas d'API pour obtenir la valeur du registration ID de l'appareil, le développeur doit obtenir le registration ID côté client et le télécharger sur le serveur du développeur pour stockage.

Adresse d'appel

https://pushapi-sgp.engagelab.com/v4/devices

Interroger le nombre de tags sous un AppKey

URL de destination

              
              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 d'appel

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

            

Paramètres de la requête

• Tag : Interroge la chaîne de tag spécifiée, champ obligatoire, jusqu'à 1000 tags peuvent être interrogés à la fois (tags=tag1&tags=tag2&tags=tag3)
• platform : Interroge la plateforme spécifiée, champ obligatoire, valeurs possibles : android, ios, hmos. Les autres valeurs ne sont pas autorisées.

Exemples de réponse

• Une réponse réussie retournera un objet JSON contenant un champ tagsCount. Il s'agit d'une collection de paires clé-valeur où la clé est le nom du tag et la valeur est le nombre de ce tag.
• En cas d'échec, un objet JSON contenant les informations d'erreur sera retourné. Le champ code indique le code d'erreur et le champ message indique le message d'erreur.

Retour réussi

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

            

Retour en cas d'échec

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

            

Interroger les alias et labels d'un appareil

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

Adresse d'appel

              
              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ètre de requête

• N/A

Exemple de retour

Retour réussi

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

            

Données retournées

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

            

• Si la statistique n'est pas trouvée, elle est nulle, sinon il s'agit de la valeur de la statistique.

Définir l'alias et le label de l'appareil

• Met à jour les attributs spécifiés de l'appareil actuel, prend actuellement en charge les tags et l'alias.

Adresse d'appel

              
              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 la requête

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

            

Paramètre de requête

• tags : prend en charge add, remove ou chaîne vide. Lorsque le paramètre tags est une chaîne vide, cela signifie effacer tous les tags ; sous add/remove, le tag spécifié est ajouté ou supprimé ;
• alias : Met à jour l'attribut alias de l'appareil ; lorsque l'alias est une chaîne vide, supprime l'alias de l'appareil spécifié.

Exemple de retour

Retour réussi

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

            

Données retournées

              
              success

            

Retour en cas d'échec

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

            

Supprimer l'appareil

• Supprime l'appareil.

Adresse d'appel

              
              DELETE /v4/devices/{registration_id}

            

Exemple de requête

En-tête de requête

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

            

Données de la requête

• N/A

Paramètres de la requête

• N/A

Exemple de retour

Retour réussi

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

            

Données retournées

              
              success

            

Retour en cas d'échec

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

            

Interroger la liste des tags

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

Adresse d'appel

              
              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 la requête

• Aucun

Exemple de requête

Retour réussi

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

            

Données retournées

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

            

• La valeur de la statistique est nulle si aucune statistique n'est trouvée, sinon il s'agit de la valeur de la statistique.

Interroger la relation de liaison entre appareil et tag

• Vérifiez si un appareil est sous le tag.

Adresse d'appel

              
              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 la requête

• registration_id Obligatoire, registration_id de l'appareil

Exemple de retour

Retour réussi

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

            

Données retournées

              
              {"result": true/false}

            

Mettre à jour les tags

• Ajouter ou supprimer des appareils pour un tag.

Adresse d'appel

              
              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 la requête

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

            

Paramètres de la requête

• action : type d'action, avec deux options : "add", "remove", qui identifie si la requête est pour "ajouter" ou "supprimer".
• registration_ids : Le registration_id de l'appareil à ajouter/supprimer.
• add/remove prend en charge jusqu'à 1000 appareils chacun.

Exemple de retour

Retour réussi

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

            

Données retournées

              
              success

            

Retour en cas d'échec

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

            

Supprimer un tag

Supprime un tag, ainsi que l'association entre le tag et l'appareil.

Adresse d'appel

              
              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 la requête

• platform est un paramètre optionnel, si non renseigné, il prend par défaut toutes les plateformes.

Exemple de retour

Retour réussi

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

            

Données retournées success

Retour en cas d'échec

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

            

Interroger un alias (relation de liaison avec l'appareil)

              
              GET /v4/aliases/{alias_value}

            

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

Adresse d'appel

              
              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 la requête

• platform est un paramètre optionnel, si non renseigné, il prend par défaut toutes les plateformes.

Exemple de retour

Retour réussi

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

            

Données retournées

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

            

• La valeur de la statistique est nulle si aucune statistique n'est trouvée, sinon il s'agit de la valeur de la statistique.

Supprimer un alias

Supprime un alias et la relation de liaison entre l'alias et l'appareil.

              
              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 la requête

• platform est un paramètre optionnel, si non renseigné, il prend par défaut toutes les plateformes.

Exemple de retour

• Succès

              
                success

            

• Échec

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

            

Obtenir le statut en ligne de l'utilisateur

Adresse d'appel

              
              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 la requête

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

            

Paramètres de la requête

• registration_ids : registration_id utilisateur à vérifier en ligne, prend en charge jusqu'à 1000 registration_ids.
• Vous devez demander un Appkey ayant activé ce service avant de pouvoir appeler cette API.

Exemple de retour

Retour réussi

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

            

Données retournées

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

            

Données retournées

• online
  • true : en ligne depuis 10 minutes ou moins ;
  • false : pas en ligne depuis 10 minutes ;
• last_online_time
  • Quand online est true, ce champ n'est pas retourné.
  • Quand online est false et que le champ n'est pas retourné, alors la dernière connexion date de deux jours ;
• La vérification échouera pour un regid invalide ou un regid qui n'appartient pas à l'appkey.

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

Interrogez les informations de quota associées à l'AppKey, la plateforme et le tag spécifiés. Le nombre de tags dans une seule requête ne peut pas dépasser 1 000.

Adresse d'appel

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

            

Retour réussi

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

            

Définition des champs de retour :

• totalTagQuota : Indique le quota total de tags sous l'application.
• useTagQuota : Indique le quota de tags utilisé.
• totalAliasQuota : Indique le quota total d'alias sous l'application.
• useAliasQuota : Indique le quota d'alias utilisé.
• tagUidQuota : Indique le quota du nombre d'appareils pour un tag unique.
• useUidQuota : Indique le détail du nombre d'appareils liés à chaque tag.

Retour en cas d'échec

              
              {
    "error": {
        "code": 27002,
        "message": "Illegal parameter"
    }
}

            

Codes d'état HTTP

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

Code de retour métier