Teilen Sie:
){kind=small}
Als ausgebildeter Schauspieler mit einer Dissertation in Standup-Comedy bin ich über die Meetup-Szene zur PHP-Entwicklung gekommen. Man findet mich, wenn ich über Technik spreche oder schreibe, oder wenn ich seltsame Platten aus meiner Vinylsammlung spiele oder kaufe.
Einführung in die Vorlagenverwaltung für Verify
Lesedauer: 4 Minuten
Entwickler können jetzt die Nachricht, die mit einem Einmaliges Passwort (OTP) gesendet werden, anstatt die Standardvorlage von Vonage zu verwenden. Diese Funktionalität ist sehr umfangreich. In diesem Artikel gehen wir darauf ein, wie sie implementiert wird und wie sie funktioniert.
Die Vorlagenverwaltung ermöglicht es Entwicklern, die OTP-Zustellungsnachricht per SMS oder Voice in jedem unterstützten Gebietsschema zu ändern. Diese sind bekannt als benutzerdefinierte Vorlagen. Eine neue Verify-Anforderung kann entweder das Gebietsschema erkennen, an das die Anforderung gesendet wird, oder ein in der Anforderung angegebenes Gebietsschema verwenden. Verify prüft dann, ob Sie eine benutzerdefinierte Vorlage für das betreffende Gebietsschema und den betreffenden Kanal erstellt haben, und verwendet diese, wenn sie vorhanden ist. Ist dies nicht der Fall, wird versucht, eine Standardvorlage von Vonage zu verwenden, und wenn Sie ein nicht unterstütztes Gebietsschema in diesem Kanal verwenden, wird schließlich en_US als Standard verwendet.
Die Funktion "Template Management" besteht aus einer Reihe von 10 neuen API-Endpunkten für Verify, die gemäß unseren HAL-Standards von Vonage.
Es gibt zwei wichtige Einheiten in benutzerdefinierten Vorlagen. Da Vorlagen das Potenzial haben, sehr groß zu werden (denken Sie daran, dass eine Vorlage, die für 15 Gebietsschemata in allen drei Kanälen verwendet wird, 45 separate Kombinationen bedeutet), wird die benutzerdefinierte Vorlage in zwei logische Teile aufgeteilt:
* Die template hat einen eindeutigen Namen und enthält eine GUID sowie die Angabe, ob es sich um die Standardvorlage für diesen Kanal und dieses Gebietsschema handelt (sie wird bei der Erstellung immer auf Standard gesetzt und kann später geändert werden)
* template_fragments, die alle Entitäten mit einer Viele-zu-Eins-Beziehung zu einer template. Die an die Vorlage angehängten Fragmente sind eindeutige Kombinationen aus locale und channeldie ihre eigene GUID haben, den text Inhalt der Vorlage und Zeitstempel.
Bei der Erstellung von Fragmenten stehen eine Reihe statischer Variablen zur Verfügung, die im Nachrichtentext verwendet werden können. Wichtig ist hier nur, dass die Nachricht den Code enthalten muss enthalten muss, der im Text durch ${code}. Es gibt noch weitere reservierte statische Variablen, hier sind sie alle aufgeführt:
${code}- den Code, den der Endnutzer eingeben muss${brand}- der in der Anfrage verwendete Markenparameter${time-limit}- Ganzzahl, die die Verfallszeit angibt${time-limit-unit}- String, der die Zeiteinheit angibt
Gehen wir den glücklichen Pfad durch, um eine benutzerdefinierte Vorlage zu zeigen, die für zwei Gebietsschemata verwendet wird en-gb und fr_fr für die SMS-Zustellung. Wenn Sie sich derzeit bei der API-Plattform von Vonage anmelden und eine Testanfrage per. SMS erhalten Sie die folgende Nachricht, vorausgesetzt, Sie haben die brand als "ACME" gesendet haben:
ACME code: 5244. Valid for 3 minutes
OK, das wollen wir ändern. Zunächst müssen wir die Vorlage mit der folgenden Anfrage erstellen:
POST https://api.nexmo.com/v2/verify/templates
{
"name": "acme-template"
}Sie erhalten eine HTTP 201, die Sie darüber informiert, dass sie erstellt wurde:
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"
}
}
}Wir müssen nun zwei Fragmente für unsere beiden Gebietsschemata erstellen. Dies geschieht mit den folgenden zwei Anfragen:
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}"
}Beide sollten 201 Antworten liefern. Unsere Anpassung ist abgeschlossen, so dass es insgesamt vier Methoden gibt, um diese beiden Meldungen auszulösen:
Dieses Beispiel einer neuen Verify-Anfrage führt zu der benutzerdefinierten en_GB Nachricht:
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"
}
]
}
Der Grund dafür, dass die en-gb Vorlage hier automatisch übernommen wird, liegt daran, dass Verify erkannt hat, dass die to Nummer eine britische Nummer enthält und daher der Vorlage zugeordnet wird. Sie können jedoch auch die Vorlage locale zu verwenden. Ein Anwendungsfall wäre z. B., dass Sie an eine kanadische Nummer senden (wo die Amtssprachen sowohl Englisch als auch Französisch sind), aber sicherstellen möchten, dass Englisch verwendet wird:
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"
}
]
}Diese beiden Situationen können auch mit unserer französischen Übersetzung abgedeckt werden.
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! Schließlich können Sie sie an eine vietnamesische Nummer senden, aber angeben, dass Sie die französische Vorlage wünschen:
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"
}
]
}
Die Entscheidung, welcher Ort gesendet wird, ist im Wesentlichen ein "Netz". Da Sie eine ganze Reihe von Optionen haben, sieht dieser Entscheidungsbaum wie folgt aus:
Verify locale logic
Es ist wichtig anzumerken, dass es am Ende des Prozesses keinen "Fehler" gibt, auch wenn er recht komplex erscheint. Wenn alles andere fehlschlägt, erhalten Sie eine Standardvorlage von Vonage in englischer Sprache mit einem Code. Endbenutzer sind vielleicht nicht in der Lage, den gesamten Text zu verstehen, aber es ist sehr wahrscheinlich, dass sie einen Code nach einem Doppelpunkt erkennen.
Hier sind einige häufige Fehler, die bei der Verwendung von benutzerdefinierten Vorlagen auftreten können:
Der Account ist nicht aktiviert
Während Lesevorlagen allen Nutzern zur Verfügung stehen, muss das Schreiben benutzerdefinierter Vorlagen in Ihrem Account aktiviert sein. Bitte wenden Sie sich an Ihren Account Manager oder an den Support, um diese Funktion zu aktivieren.
Vorlage oder Fragment vorhanden
Jede Vorlage muss einen eindeutigen Namen haben, und jedes Fragment auf dieser Vorlage muss ein kombinierter eindeutiger Eintrag für ein Gebietsschema und einen Kanal sein.
Versuch, eine Vorlage mit Fragmenten zu löschen
Sie können eine Vorlage nicht löschen, wenn sie bereits Fragmente enthält. Sie können die HAL-Felder für die Erkennung in der Antwort "Vorlage abrufen" verwenden, um die IDs der vorhandenen Fragmente zu durchsuchen, bevor Sie die Vorlage selbst löschen.
Nicht verwenden
${code}im Text
Wenn Sie ein Fragment erstellen, müssen Sie den Code in den Text einfügen. Wenn Sie den Code nicht an den Endnutzer weitergeben, verfügen Sie nicht über ein Zwei-Faktor-Authentifizierungssystem - die API lässt Sie also nicht zu, dies zu tun.
Maximale Anzahl von Vorlagen
Es gibt eine Obergrenze von 10 Vorlagen pro Benutzer, und der Versuch, mehr zu erstellen, führt zu einer Fehlermeldung.
Obwohl die benutzerdefinierten Vorlagen eine relativ große Erweiterung von Verify darstellen, sind wir noch nicht fertig: Weitere Funktionen werden bald folgen! In der Zwischenzeit können Sie uns auf unserem Gemeinschaft Slack kontaktieren, wenn Sie Fragen oder Feedback zu Verify haben.
Teilen Sie:
Als ausgebildeter Schauspieler mit einer Dissertation in Standup-Comedy bin ich über die Meetup-Szene zur PHP-Entwicklung gekommen. Man findet mich, wenn ich über Technik spreche oder schreibe, oder wenn ich seltsame Platten aus meiner Vinylsammlung spiele oder kaufe.