Partager:
){kind=small}
Acteur de formation avec une thèse sur la comédie, je suis venu au développement PHP par le biais de la scène des rencontres. Vous pouvez me trouver en train de parler et d'écrire sur la technologie, ou de jouer/acheter des disques bizarres de ma collection de vinyles.
Introduction de la gestion des modèles pour Verify
Temps de lecture : 5 minutes
Les développeurs peuvent désormais personnaliser le message envoyé avec un mot de passe à usage unique (OTP) plutôt que d'utiliser le modèle par défaut de Vonage. Cette fonctionnalité est étendue, c'est pourquoi dans cet article, nous verrons comment l'implémenter et comment elle fonctionne.
La gestion des modèles permet aux développeurs de modifier le message de remise de l'OTP par SMS ou Voice dans toutes les localités prises en charge. Ces modèles sont connus sous le nom de modèles personnalisés. Une nouvelle demande de Verify peut soit détecter la locale à laquelle la demande est envoyée, soit utiliser une locale spécifiée dans la demande. Verify vérifie alors si vous avez créé un modèle personnalisé pour cette locale et ce canal et l'utilise si c'est le cas. Si ce n'est pas le cas, il tente d'utiliser un modèle standard de Vonage, et si vous utilisez une locale non prise en charge dans ce canal, il utilise finalement par défaut en_US.
La fonction de gestion des modèles est un ensemble de 10 nouveaux points d'extrémité de l'API à Verify, codés selon nos normes HAL de Vonage. normes HAL de Vonage.
Les modèles personnalisés comportent deux entités importantes. Comme les modèles peuvent devenir très volumineux (par exemple, un modèle utilisé pour 15 localités sur les trois canaux, soit 45 combinaisons distinctes), le modèle personnalisé est divisé en deux parties logiques :
* Le modèle template qui a un nom unique et contient un GUID et s'il s'agit du modèle par défaut pour ce canal et cette locale (ils sont toujours définis par défaut lors de la création et peuvent être modifiés ultérieurement).
* template_fragmentsqui sont toutes des entités ayant une relation de plusieurs à un avec une entité template. Les fragments attachés au modèle sont des combinaisons uniques de locale et channelqui ont leur propre GUID, le contenu du modèle et les horodatages. text le contenu du modèle et l'horodatage.
Lors de la création de fragments, quelques variables statiques sont disponibles pour être utilisées dans le texte du message. La seule chose importante à noter ici est que le message doit contenir le code qui est représenté dans le texte par ${code}. Il existe d'autres variables statiques réservées, les voici toutes :
${code}- le code à saisir par l'utilisateur final${brand}- le paramètre de marque utilisé dans la demande${time-limit}- nombre entier représentant le délai d'expiration${time-limit-unit}- chaîne de caractères représentant l'unité de temps
Passons par le chemin heureux pour montrer qu'un modèle personnalisé est utilisé pour deux locales en-gb et fr_fr pour la livraison de SMS. Actuellement, l'inscription à la plateforme API de Vonage et l'envoi d'une demande de test par . SMS vous donnera le message suivant, en supposant que vous avez envoyé le brand comme "ACME" :
ACME code: 5244. Valid for 3 minutes
OK, changeons cela. Tout d'abord, nous devons créer le modèle à l'aide de la requête suivante :
POST https://api.nexmo.com/v2/verify/templates
{
"name": "acme-template"
}Vous obtiendrez un message HTTP 201 pour vous informer qu'il a été créé :
HTTP 201
{
"template_id": "8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9",
"name": "acme-template",
"is_default": true,
"_links": {
"self": {
"href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9"
},
"fragments": {
"href": "https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments"
}
}
}Nous devons maintenant créer deux fragments pour nos deux locales. Cela se fait avec les deux requêtes suivantes :
POST https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments
{
"channel": "sms",
"locale": "en-gb",
"text": "Thank you for continuing to use ${brand}! Your OTP is: ${code}"
}
POST https://api.nexmo.com/v2/verify/templates/8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9/template_fragments
{
"channel": "sms",
"locale": "fr-fr",
"text": "Merci de continuer à utiliser ${brand}! Votre OTP est: ${code}"
}Les deux devraient donner 201 réponses. Notre personnalisation étant complète, il existe quatre méthodes au total pour déclencher ces deux messages :
Cet exemple de nouvelle demande de Verify aboutira au message personnalisé suivant en_GB message personnalisé :
POST
https://api.nexmo.com/v2/verify
{
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "447700900000"
}
]
}
La raison pour laquelle le modèle en-gb modèle est repris automatiquement ici, c'est parce que Verify a détecté que le numéro contient un numéro britannique. to contient un numéro britannique et qu'il correspond donc au modèle. Vous pouvez cependant spécifier le modèle locale à utiliser à la place, par exemple si vous envoyez un message à un numéro canadien (où les langues officielles sont l'anglais et le français), mais que vous voulez vous assurer que l'anglais est utilisé :
POST
https://api.nexmo.com/v2/verify
{
"locale": "en-gb"
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "17700900000"
}
]
}Ces deux situations peuvent également être utilisées avec notre traduction en français.
POST
https://api.nexmo.com/v2/verify
{
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "847700900000"
}
]
}Très Bon ! Enfin, vous pouvez l'envoyer à un numéro vietnamien, mais en précisant que vous voulez le modèle français :
POST
https://api.nexmo.com/v2/verify
{
"locale": "fr-fr"
"channel_timeout": 180,
"client_ref": "my-personal-reference",
"brand": "ACME",
"template_id": "4ed3027d-8762-44a0-aa3f-c393717413a4",
"workflow": [
{
"channel": "sms",
"to": "847700900000"
}
]
}
Le choix de la localité à envoyer est essentiellement un "filet". Comme vous avez plusieurs options, cet arbre de décision ressemble à ceci :
Verify locale logic
Il est important de noter que, bien que cela puisse sembler assez complexe, il n'y a pas d'"erreur" à la fin de la procédure. En cas d'échec, vous obtenez un modèle Vonage par défaut en anglais avec un code. Les utilisateurs finaux ne seront peut-être pas en mesure de comprendre l'intégralité du texte, mais ils reconnaîtront très probablement un code après deux points.
Voici quelques erreurs courantes que vous pouvez rencontrer lorsque vous essayez d'utiliser des modèles personnalisés :
Le compte n'est pas activé
Alors que les modèles de lecture sont disponibles pour tous les utilisateurs, la rédaction de modèles personnalisés doit être activée sur votre Account. Veuillez contacter votre Account manager ou vous adresser à l'assistance pour activer cette fonctionnalité.
Le modèle ou le fragment existe
Chaque modèle doit avoir un nom unique et chaque fragment de ce modèle doit être une entrée unique combinée pour une locale et un canal.
Tentative de suppression d'un modèle avec des fragments
Vous ne pouvez pas supprimer un modèle s'il existe des fragments. Vous pouvez utiliser les champs HAL de découverte dans la réponse get template pour parcourir les ID des fragments existants à supprimer avant de supprimer le modèle lui-même.
Ne pas utiliser
${code}dans le texte
Lorsque vous créez un fragment, vous devez inclure le code dans le texte. Si vous ne fournissez pas le code à l'utilisateur final, vous ne disposez pas d'un système d'authentification à deux facteurs - l'API ne vous permettra donc pas de le faire.
Nombre maximum de modèles
Le nombre de modèles est limité à 10 par utilisateur, et toute tentative d'en générer davantage se soldera par une erreur.
Bien que les modèles personnalisés constituent un ajout relativement important à Verify, nous ne sommes pas encore au bout de nos peines : d'autres fonctionnalités à surveiller sont à venir ! En attendant, vous pouvez nous contacter sur notre communauté Slack si vous avez des questions ou des commentaires sur Verify.
Partager:
Acteur de formation avec une thèse sur la comédie, je suis venu au développement PHP par le biais de la scène des rencontres. Vous pouvez me trouver en train de parler et d'écrire sur la technologie, ou de jouer/acheter des disques bizarres de ma collection de vinyles.