Создание USSD-регистрации на мероприятие с помощью Africa’s Talking, NodeJS, Mongo и Docker

От настройки до сборки и развертывания

Введение

В этом руководстве мы расскажем, как создать простую службу регистрации событий на платформе Africa’s Talking with Node. Традиционно использование USSD было сложной задачей. Сначала просто построить, но становится сложнее, когда вам нужно отслеживать состояние и управлять базами данных. Мы будем использовать замечательную библиотеку под названием ussd-builder, которая поможет нам управлять нашим состоянием при регистрации пользователей — это также должно значительно упростить создание USSD.

Подготовка

Создайте папку проекта и инициализируйте наше приложение:

mkdir registration-ussd && cd registration-ussd
npm init -y

Далее установим нужные нам библиотеки:

npm install — save express ussd-builder dotenv mongoose

Mongoose помогает нам работать с нашим экземпляром MongoDB намного проще. Чуть позже мы создадим экземпляр MongoDB, давайте сначала запустим наше приложение.

Создайте файл index.js в корневой папке и добавьте следующий код:

const express = require(‘express’);
const app = express();
app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.listen(3000, () => console.log(‘App running on port 3000’));

На своем терминале запустите:

node index.js

… и вы должны увидеть вывод на своем терминале.

Создание вашей базы данных

Мы будем создавать нашу базу данных на MongoDB. Вот статья о том, как начать работу с платформой Mongo. Как только у нас будет наша БД, мы сможем подключиться к ней в нашем приложении через Mongoose. Прежде чем мы напишем код, создайте файл .env и добавьте в него следующее:

DATABASE_URL=<Add_your_remote_mongo_uri_here>

Затем отредактируйте файл index.js, чтобы он выглядел следующим образом:

require("dotenv").config();
const express = require("express");
const mongoose = require("mongoose");
const mongoString = process.env.DATABASE_URL;
mongoose.connect(mongoString);
const database = mongoose.connection;
database.on("error", (error) => {
console.log(error);
});
database.once("connected", () => {
console.log("Database connected...");
});
const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.listen(3000, () => {
console.log("What's popping? We're connected");
});

Что мы добавили выше:

Мы ввели dotenv, чтобы помочь нам читать значения из файла .env.
Мы создали соединение с нашей удаленной базой данных Mongo с помощью mongoose.connect(mongoString)
Сделано несколько проверок, чтобы убедиться, что соединение с MongoDB работает.

На этом этапе мы можем перезапустить наш код для подключения к нашей БД:

node index.js

Вы должны увидеть этот вывод в терминале:

Database connected....

What's popping? We're connected

Создание модели данных

Далее нам нужно определить схему наших данных. Создайте папку models и в ней создайте новый файл models.js

mkdir models && cd models
touch models.js

Далее мы определим нашу модель и экспортируем ее:

const mongoose = require("mongoose");
const dataSchema = new mongoose.Schema({
name: {
required: true,
type: String
},
tickets: {
required: true,
type: Number
}
});
module.exports = mongoose.model("Data", dataSchema);

Мы фиксируем только имена участников и номера билетов. Мы могли бы расширить эти данные, если это необходимо, например, если бы мы хотели зафиксировать проблемы с питанием.

Создание потока USSD

Прежде чем мы перейдем к построению нашего потока USSD, давайте еще раз посмотрим, что это такое и для чего он хорош.

USSD — это технология 2G, которая позволяет пользователям как обычных телефонов, так и смартфонов получать доступ к услугам без необходимости доступа в Интернет. USSD довольно простой, состоящий из текстового интерфейса с диалоговым/меню-ориентированным подходом. Это может быть весьма полезно для многочисленных вариантов использования:

Простые транзакционные интерфейсы, например. банковское дело
Простой сбор данных, например. опрос

Добавьте изображение реального мира USSD

Теперь, когда мы разобрались с этим, давайте создадим наш поток:

В этом случае мы будем регистрировать пользователей на вымышленную Zizi Conference. Пользователи смогут зарегистрировать свое имя, количество билетов, и мы также отправим им текст подтверждения. Простой легко следовать потоку.

Прежде чем мы начнем, мы создадим нашу учетную запись Africa’s Talking.

Создание учетной записи Talking Account в Африке

Сначала зайдите на панель инструментов Говорящая Африка. "Войдите или создайте новую учетную запись". Существует быстрый процесс проверки, который помогает нам узнать, что вы настоящий.

Далее мы перейдем к среде песочницы и создадим шорткод USSD. Выбери крутой номер, будем его много набирать. Если вам нужен краткий обзор приборной панели AT, вот короткое видео:

https://www.youtube.com/watch?v=IEXrOq1sExM&

https://youtu.be/IEXrOq1sExM

Запомните свой USSD-код, он понадобится нам сразу после этого следующего раздела.

Использование библиотеки `ussd-builder`

Как упоминалось ранее, эта библиотека — отличный проект, который создает классную библиотеку на основе FSM для USSD. Вы можете ознакомиться с их работой и документацией здесь.

Прямо под операторами app.use в файле index.js мы добавляем следующий код:

...
let menu = new UssdMenu();
menu.startState({
run: () => {
// use menu.con() to send response without terminating session
menu.con('Welcome! Ready to register for the Zizi Conference:' +
'\n1. Get started' +
'\n2. Get out!');
},
// next object links to next state based on user input
next: {
'1': 'register',
'2': 'quit'
}
});
menu.state('register', {
run: () => {
menu.con('Before we go ahead, whats your name?');
},
next: {
'*[a-zA-Z]+': 'register.tickets'
}
});
menu.state('register.tickets', {
run: () => {
let name = menu.val;
dataToSave.name = name;
console.log(dataToSave);
menu.con('How many tickets would you like to reserve?');
},
next: {
// using regex to match user input to next state
'*\\d+': 'end'
}
});
menu.state('end', {
run: async () => {
let tickets = menu.val;
dataToSave.tickets = tickets;
console.log(dataToSave);
// Save the data
const data = new Model({
name: dataToSave.name,
tickets: dataToSave.tickets
});
const dataSaved = await data.save();

menu.end('Awesome! We have your tickets reserved. Sending a confirmation text shortly.');
}
});
menu.state('quit', {
run: () => {
menu.end("Goodbye :)");
}
});
// Registering USSD handler with Express
app.post('/ussd', (req, res)=>{
menu.run(req.body, ussdResult => {
res.send(ussdResult);
});
});
...

Приведенный выше код помогает нам создавать пути/состояния вокруг USSD-диаграммы, представленной ниже.

Запускаем наше приложение

Чтобы запустить приложение, нам нужно разместить наше приложение в сети. Загрузите ngrok, чтобы туннелировать наше приложение. После того, как вы установили ngrok, запустите

./ngrok http 3000

Получив пользовательскую ссылку от ngrok, откройте панель управления Africa’s Talking и вставьте ее в раздел обратного вызова USSD:

Как только это будет сделано, нам нужно протестировать наше приложение на симуляторе Africa’s Talking. Симулятор позволяет вам визуализировать ваш USSD, прежде чем вы начнете использовать реальный код.

(Необязательно) Добавление SMS-уведомлений в проект

В этом разделе мы добавим компонент SMS, который сообщает нашему участнику, сколько билетов он зарезервировал. Для этого нам нужно установить пакет africastalking npm.

npm i -s africastalking

Чуть ниже, где объявлена переменная dataToSave, мы можем добавить следующий код:

const atCredentials = {
apiKey: process.env.AT_SANDBOX_APIKEY,
username: process.env.AT_SANDBOX_USERNAME
};
const AfricasTalking = require("africastalking")(atCredentials);
const sms = AfricasTalking.SMS;

После этого мы можем получить наше имя пользователя, которое в данном случае sandbox, и ваш ключ API здесь, а затем добавить их в ваш файл .env:

AT_SANDBOX_USERNAME=
AT_SANDBOX_APIKEY=

Далее мы фактически отправим сообщение участнику. Чуть ниже точки, в которой мы сохраняем данные в endState, мы добавим функцию отправки сообщения:

...
const dataSaved = await data.save();
const options = {
to: menu.args.phoneNumber,
message: `Hi ${dataToSave.name}, we've reserved ${dataToSave.tickets} tickets for you.`
}
await sms.send(options);
...

Это позволяет нам отправить индивидуальное сообщение нашему участнику, подтверждающее участие.

(Необязательно) Расширение приложения

Это будет конец приложения, по крайней мере, для учебника, но мы можем сделать гораздо больше и создать полностью работающее приложение для регистрации событий с веб-интерфейсом и многим другим. Если вы хотите увидеть это, оставьте комментарий ниже, и мы сделаем вторую часть статьи.

Чтобы узнать больше о продуктах Africa’s Talking:

Документация по сборке AT: https://developers.africastalking.com/
Больше о нашей культуре в нашем блоге: https://blog.africastalking.com
Присоединяйтесь к нашему сообществу разработчиков-фрилансеров: WhatsApp, Facebook, Slack.