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 d'un appareil côté serveur. Lors de son utilisation, veillez à ce que les tags définis côté serveur ne soient pas écrasés par le côté client.

• Si vous n'êtes pas familier avec les tags, la logique d'alias suggère de n'utiliser que le client ou le serveur.
• Si vous l'utilisez des deux côtés en même temps, veuillez confirmer que votre application peut gérer la synchronisation des tags et des alias.

Pour plus d'informations sur les tags et les alias, veuillez consulter la description de l'API de la plateforme client correspondante.

• web-tag,alias

Règles et restrictions d'utilisation des TAG

• Limite de quantité de TAG : Sous un seul appkey, vous pouvez créer jusqu'à 100 000 tags.
• Limite de longueur de 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 de TAG par appareil : Chaque appareil peut lier jusqu'à 100 tags.
• Limite de quantité 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, pas à plusieurs appareils. De même, chaque appareil dans la portée de l'appkey ne peut être associé qu'à un seul alias, pas à plusieurs alias.
• Limite de quantité d'alias : Sous un seul appkey, vous pouvez créer jusqu'à 100 000 alias.
• Limite de longueur d'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

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 contient trois ensembles d'API : device, tag et alias. Ainsi :

• device est utilisé pour interroger/définir diverses propriétés de l'appareil, y compris les tags, 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'information clé à utiliser est le registration ID :

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

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

Interroger le nombre de tags sous un AppKey

URL de destination

              
              GET /v4/tags_count

            

Exemple de requête

En-têtes de la requête

              
              GET /v4/tags_count
Authorization: Basic (chaîne d'authentification base64)
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 : Interroger la chaîne de tags spécifiée, champ obligatoire, jusqu'à 1000 tags peuvent être interrogés à la fois (tags=tag1&tags=tag2&tags=tag3)
• platform : Interroger la plateforme spécifiée, champ obligatoire, valeurs autorisées : android, ios, autres valeurs non autorisées.

Exemples de réponse

• Une réponse réussie renverra 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.
• Si la requête échoue, un objet JSON contenant les informations d'erreur sera renvoyé. 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 échoué

              
              {
    "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, l'alias.

Adresse d'appel

              
              GET /v4/devices/{registration_id}

            

Exemple de requête

En-tête de la requête

              
              GET /v4/devices/{registration_id}
  Authorization: Basic (chaîne d'authentification base64) 
  Accept: application/json

            

Paramètre 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

              
              {"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

• Mettre à jour les attributs spécifiés de l'appareil actuel, actuellement supporte les tags, l'alias.

Adresse d'appel

              
              POST /v4/devices/{registration_id}

            

Exemple de requête

En-tête de la requête

              
              POST /v4/devices/{registration_id}
   Authorization: Basic (chaîne d'authentification base64)
   Accept: application/json

            

Données de la requête

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

            

Paramètre de la requête

• tags : supporte 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 échoué

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

            

Supprimer l'appareil

• Supprimer l'appareil.

Adresse d'appel

              
              DELETE /v4/devices/{registration_id}

            

Exemple de requête

En-tête de la requête

              
              DELETE /v4/devices/{registration_id}
   Authorization: Basic (chaîne d'authentification base64)
   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 échoué

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

            

Interroger la liste des tags

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

Adresse d'appel

              
              GET /v4/tags/

            

Exemple de requête

En-tête de la requête

              
              GET /v4/tags/
   Authorization: Basic (chaîne d'authentification base64)
   Accept: application/json

            

Paramètres de la requête

• Aucun

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

            

• 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 l'appareil et le tag

• Vérifier 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 la requête

              
              GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
  Authorization: Basic (chaîne d'authentification base64) 
  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 la requête

              
              POST /v4/tags/{tag_value}
  Authorization: Basic (chaîne d'authentification base64) 
  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 échoué

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

              
              DELETE /v4/tags/{tag_value}?platform=web
   Authorization: Basic (chaîne d'authentification base64)
   Accept: application/json

            

Paramètres de la requête

• platform est un paramètre optionnel, si non renseigné, il s'applique à 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 échoué

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

            

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

              
              GET /v4/aliases/{alias_value}

            

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

Adresse d'appel

              
              GET /v4/aliases/{alias_value}

            

Exemple de requête

En-tête de la requête

              
              GET /v4/aliases/{alias_value}?platform=web
   Authorization: Basic (chaîne d'authentification base64)
   Accept: application/json

            

Paramètres de la requête

• platform est un paramètre optionnel, si non renseigné, il s'applique à 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 la requête

              
              DELETE /v4/aliases/{alias_value}?platform=web
   Authorization: Basic (chaîne d'authentification base64)
   Accept: application/json

            

Paramètres de la requête

• platform est un paramètre optionnel, si non renseigné, il s'applique à 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 la requête

              
              POST /v4/devices/status/
  Authorization: Basic (chaîne d'authentification base64) 
  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
  • Lorsque online est true, ce champ n'est pas retourné.
  • lorsque 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 n'appartenant pas à l'appkey.

Interface de requête d'informations de quota TAG/alias

Interroger les informations de quota associées de l'AppKey, de la plateforme et du 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 (chaîne d'authentification base64)
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=='

            

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