Compartir:
){kind=small}
Actor de formación con una disertación sobre la comedia, llegué al desarrollo de PHP a través de la escena de las reuniones. Puedes encontrarme hablando y escribiendo sobre tecnología, o tocando/comprando discos raros de mi colección de vinilos.
Presentación de la gestión de plantillas para Verify
Tiempo de lectura: 4 minutos
Los desarrolladores pueden ahora personalizar el mensaje enviado con una contraseña de un solo uso (OTP) en lugar de utilizar la plantilla predeterminada de Vonage. Esta funcionalidad es amplia, por lo que en este artículo veremos cómo implementarla y cómo funciona.
La gestión de plantillas permite a los desarrolladores cambiar el mensaje de entrega OTP en SMS o Voice a través de cualquier localización soportada. Estas se conocen como plantillas personalizadas. Una nueva solicitud de Verify puede detectar la configuración regional a la que se envía la solicitud o utilizar una configuración regional especificada en la solicitud. Verify, a continuación, comprueba si ha creado una plantilla personalizada para esa configuración regional y canal y la utiliza si está presente. Si no, intenta utilizar una plantilla estándar de Vonage y, si estás utilizando una configuración regional no admitida dentro de ese canal, finalmente utiliza por defecto en_US.
La función de administración de plantillas es un conjunto de 10 nuevos puntos finales de API para Verify, codificados según nuestros estándares HAL de Vonage.
Hay dos entidades importantes en las plantillas personalizadas. Dado que las plantillas pueden llegar a ser muy grandes (por ejemplo, si se utiliza una plantilla para 15 configuraciones regionales en los tres canales, se obtienen 45 combinaciones distintas), la plantilla personalizada se divide en dos partes lógicas:
* El template que tiene un nombre único y contiene un GUID y si es la plantilla por defecto para ese canal y configuración regional (siempre se establecen por defecto cuando se crean y se pueden cambiar más tarde).
* template_fragmentsque son todas entidades con una relación de muchos a uno con una entidad template. Los fragmentos adjuntos a la plantilla son combinaciones únicas de locale y channelque tienen su propio GUID, el text contenido de la plantilla y marcas de tiempo.
Al crear fragmentos, se dispone de un par de variables estáticas para utilizar dentro del texto del mensaje. Lo único importante a tener en cuenta aquí es que el mensaje debe contener el código que se representa en el texto mediante ${code}. Hay otras variables estáticas reservadas, aquí están todas:
${code}- el código que debe introducir el usuario final${brand}- el parámetro de marca utilizado en la solicitud${time-limit}- número entero que representa la hora de expiración${time-limit-unit}- cadena que representa la unidad de tiempo
Vamos a recorrer el camino feliz para mostrar una plantilla personalizada que se utiliza para dos locales en-gb y fr_fr para la entrega de SMS. Actualmente, al registrarte en la plataforma API de Vonage y enviar una solicitud de prueba a través de. SMS te dará el siguiente mensaje, suponiendo que enviaste el archivo brand como "ACME":
ACME code: 5244. Valid for 3 minutes
Bien, vamos a cambiarlo. En primer lugar, tenemos que crear la plantilla utilizando la siguiente solicitud:
POST https://api.nexmo.com/v2/verify/templates
{
"name": "acme-template"
}Obtendrá un HTTP 201 para informarle de que se ha creado:
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"
}
}
}Ahora necesitamos crear dos fragmentos para nuestras dos locales. Esto se hace con las dos peticiones siguientes:
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}"
}Ambos deberían dar 201 respuestas. Nuestra personalización es completa, por lo que hay cuatro métodos en total para desencadenar estos dos mensajes:
Este ejemplo de nueva solicitud Verify resultará en el mensaje personalizado en_GB personalizado:
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 razón por la que la en-gb plantilla se recoge automáticamente aquí es porque Verify ha detectado que el número to contiene un número del Reino Unido, por lo que se asigna a la plantilla. Sin embargo, puede especificar el locale para utilizarlo en su lugar, por lo que un caso de uso podría ser que usted está enviando a un número canadiense (donde los idiomas oficiales son Inglés y Francés), pero quiere asegurarse de que el Inglés se utiliza:
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"
}
]
}Estas dos situaciones también pueden utilizarse con nuestra traducción al francés.
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! Por último, puedes enviarlo a un número vietnamita, pero especifica que quieres la plantilla francesa:
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"
}
]
}
Decidir qué localidad se envía es esencialmente una "red". Como tiene bastantes opciones, este árbol de decisión tiene este aspecto:
Verify locale logic
Es importante destacar que, si bien puede parecer bastante complejo, no hay ningún "error" al final del proceso. Si todo lo demás falla, obtendrás una plantilla predeterminada de Vonage en inglés con un código. Es posible que los usuarios finales no puedan entender todo el texto, pero es muy probable que reconozcan un código después de dos puntos.
Estos son algunos errores comunes que puede encontrar al intentar utilizar plantillas personalizadas:
La Account no está habilitada
Mientras que las plantillas de lectura están disponibles para todos los usuarios, la escritura de plantillas personalizadas debe estar habilitada en su Account. Póngase en contacto con su gestor de Account o hable con el servicio de asistencia para activar esta función.
Plantilla o fragmento existente
Cada plantilla debe tener un nombre único, y cada fragmento de esa plantilla debe ser una entrada única combinada para una configuración regional y un canal.
Intento de eliminar plantilla con fragmentos
No puedes borrar una plantilla si tiene fragmentos existentes. Puede utilizar los campos HAL para la detección en la respuesta get template para recorrer los ID de los fragmentos existentes que desea eliminar antes de eliminar la plantilla en sí.
No utilizar
${code}en el texto
Al crear un fragmento, debes incluir el código dentro del texto. Si no entregas el código a tu usuario final, no dispones de un sistema de autenticación de dos factores, por lo que la API no te permitirá hacerlo.
Número máximo de plantillas
Hay un límite de 10 plantillas por usuario, y cualquier intento de generar más dará lugar a un error.
Aunque las plantillas personalizadas son una incorporación relativamente importante a Verify, aún no hemos terminado: ¡pronto habrá más funciones a tener en cuenta! Mientras tanto, puede ponerse en contacto con nosotros en nuestra Slack de la comunidad si tiene preguntas o comentarios sobre Verify.
Compartir:
Actor de formación con una disertación sobre la comedia, llegué al desarrollo de PHP a través de la escena de las reuniones. Puedes encontrarme hablando y escribiendo sobre tecnología, o tocando/comprando discos raros de mi colección de vinilos.