Crie uma caça ao tesouro interativa com a SMS API e a Voice API da Nexmo

Introdução

Hoje em dia, os códigos QR estão por toda parte: no verso de cartões de visita, em folhetos ou em outdoors — onde você imaginar. Eles permitem que qualquer pessoa com um smartphone acesse informações rapidamente e, por isso, se popularizaram na última década.

Hoje vamos aproveitar essa funcionalidade para criar uma caça ao tesouro interativa por toda a sua cidade!

🔎 Um aplicativo de caça ao tesouro 🔎

Acho que não há maneira melhor de tirar seus amigos e familiares do sofá e levá-los para passear pela vizinhança do que com uma caça ao tesouro interativa. Por isso, achei que seria divertido projetar e criar algo usando as APIs de voz e SMS da Nexmo para fazer exatamente isso. Este tutorial vai explicar como criar códigos QR para esconder pelo bairro e como criar um aplicativo com Express e Node.js para gerar uma mensagem de SMS correspondente a ser enviada para um número de telefone da Nexmo, que ligará de volta para o participante com uma pista gravada! A caça ao tesouro pode continuar com quantas pistas VOCÊ quiser.

O fluxo do aplicativo:

• O usuário encontra um código QR

• Escaneia o código QR com o smartphone

• O SMS já vem preenchido com uma mensagem a ser enviada para um número de telefone da Nexmo

• O usuário clica em “Enviar”

• O aplicativo inicia uma ligação telefônica

• Gravação das jogadas-chave

• O usuário procura essa nova pista e o jogo continua!

Pré-requisitos

Para seguir este tutorial, você precisará de um Account na Vonage. Você pode se cadastrar agora para grátis , caso ainda não tenha um Account.

Mas, se você quiser pular direto para um projeto que já funcione, pode fazer um remix do aplicativo leitor de código QR direto no Glitch.

Caso contrário, em apenas algumas etapas você pode criar suas próprias pistas e seu próprio aplicativo do zero!

Registre as pistas da sua caça ao tesouro

Usando seu dispositivo de gravação preferido, grave as pistas para sua caça ao tesouro como arquivos .ogg. Aqui está um exemplo de uma das minhas pistas: [audio ogg="https://www.nexmo.com/wp-content/uploads/2019/08/clue1.ogg"]

(DICA: isso leva ao Fremont Troll, debaixo de uma ponte aqui em Seattle 😆)

troll

Criar um Account no Nexmo

Se você ainda não fez isso, crie um account gratuito no Nexmo e, como bônus extra, seu account receberá 2 euros para você começar a usar seu novo aplicativo. Acesse <${CUSTOMER_DASHBOARD_URL}/sign-up?icid=tryitfree_api-developer-adp_nexmodashbdfreetrialsignup_nav> e siga as etapas de cadastro. Ao concluir, você estará no seu painel do Nexmo.

Adquira um número de telefone da Nexmo

No painel do Nexmo, clique no Numbers item de menu no lado esquerdo.

Clique na Buy Numbers opção e você será direcionado a uma página onde poderá escolher um país, recursos, tipo e os quatro dígitos que deseja que o número tenha.

buy number dashboard

Selecione o país em que você está no momento para que a ligação seja local. Para os recursos, selecione Voice e, quanto ao tipo, tanto celular quanto telefone fixo funcionam perfeitamente.

Clique Search para ver uma lista dos números de telefone disponíveis.

Selecione um número clicando no botão laranja Buy e, em seguida, no botão laranja Buy novamente assim que aparecer a janela de confirmação.

Agora você possui um número de telefone da Nexmo. O próximo passo é criar uma aplicação no painel de controle da Nexmo.

Criar um aplicativo de voz da Nexmo

No menu à esquerda, clique no Voice item do menu.

Selecione a Create an application opção. Você será direcionado para uma página onde poderá configurar um novo aplicativo Nexmo.

Preencha o formulário com as seguintes informações:

Application name campo de texto: Enter qr code scavenger hunt

Event URL No campo de texto, digite a URL do Glitch: https://[your Glitch URL].glitch.me/events

Answer URL No campo de texto, digite novamente a URL do Glitch: https://[your Glitch URL].glitch.me/answer

Depois de inserir tudo isso, clique no botão azul Create Application .

Certifique-se de gerar um par de chaves pública/privada e salvá-lo.

Conectar tudo entre si

Agora você já tem um número da Nexmo e um aplicativo de voz; só falta conectar os dois.

Selecione a Numbers opção de menu no menu à esquerda e, em seguida, clique em Your numbers. Você será direcionado para uma página que exibe o número de telefone que acabou de adquirir.

Clique no ícone de engrenagem no lado direito da página e um menu será exibido. No Inbound Webhook URL campo, digite a URL do seu Glitch seguida de /smsInbound: https://[sua URL do Glitch].glitch.me/smsInbound`

Selecione Application na Forward to área

Selecione seu novo aplicativo na lista suspensa abaixo da Application área. Clique no botão azul Ok botão

inbound webhook

Seu novo número de voz da Nexmo já está vinculado ao seu novo aplicativo da Nexmo e, com essa última etapa, você está pronto para desenvolver seu aplicativo!

Solução de problemas

No painel do Nexmo, abaixo do seu nome e das configurações da Account, certifique-se de selecionar POST-JSON como seu MÉTODO HTTP padrão, da seguinte forma:

post json

Introdução ao Glitch

Para começar, crie um novo projeto no Glitch, escolhendo o hello-express modelo.

No package.json arquivo, selecione o Add a package menu suspenso para procurar e adicionar as seguintes dependências: nexmo, qrcode, body-parser, e dotenv.

dependency list

No início do seu server.js arquivo, vamos configurar nosso servidor Express, incluir nossas dependências e incorporar nossas credenciais do Nexmo:

// server.js
require('dotenv').config();

const express = require('express');
const bodyParser = require('body-parser')
const Nexmo = require('nexmo');
const app = express();
const assets = require('./assets');

app.use(express.static('public'));
app.use(bodyParser.json());
app.use("/assets", assets);

const nexmo = new Nexmo({
    apiKey: process.env.API_KEY,
    apiSecret: process.env.API_SECRET,
    applicationId: process.env.APP_ID,
    privateKey: `${__dirname}/${process.env.PRIVATE_KEY_PATH}`
  });

No .env arquivo, preencha as credenciais específicas da Nexmo que acabamos de criar no Painel da Nexmo:

API_KEY=**ABC123**
API_SECRET=***aBc1xYZ***
APP_ID=**2xyZ-3aBc**
PRIVATE_KEY_PATH=.data/private.key
NEXMO_NUMBER=15551234567

Substitua a chave da API, o segredo da API, o ID do aplicativo e o seu número Nexmo. Para incluir a chave privada, selecione o New File botão de alternância no canto superior esquerdo e nomeie-o .data/private.key. Nesse arquivo, cole a chave privada que você gerou ao criar seu aplicativo de voz. Esse arquivo ficará invisível no Glitch se você refazer seu código por motivos de segurança.

Criar rotas em server.js

Em seguida, abaixo dessas credenciais, além da nossa rota padrão e do listener, vamos criar algumas rotas diferentes:

// server.js
app.get('/', (req, res) => {
  res.sendFile(__dirname + '/views/index.html');
});

app.post('/events', (req, res) => {});

app.get('/answer', (req, res) => {});

app.get('/playRecording/:name', (req, res) => {});

app.post('/smsInbound', (req, res) => {});

const listener = app.listen(process.env.PORT, function() {
  console.log('Your app is listening on port ' + listener.address().port);
});

As primeiras funções que precisamos definir são para /events e /answer que responderão com a send() funcionalidade caso a resposta de status seja 200:

// server.js
app.post('/events', (req, res) => {
  res.status(200).send();
});

app.get('/answer', (req, res) => {
  res.status(200).send();
});

Em seguida, para a /playRecording rota, você fará com que o aplicativo reproduza dinamicamente as gravações das pistas da sua caça ao tesouro:

// server.js
app.get('/playRecording/:name', (req, res) => {
  let filename= req.params.name

  let ncco = [
    {
      "action": "stream",
      "streamUrl": [`${req.protocol}://${req.headers.host}/assets/${filename}`]
    }
  ];
  res.status(200).json(ncco);
});

Por fim, para a /smsInbound rota, crie uma instrução switch que determine qual pista foi encontrada. Você pode nomeá-las como quiser (recomendo ser um pouco mais criativo do que meus nomes numéricos sem graça 😂).

// server.js
app.post('/smsInbound', (req, res) => {
  let keyword;
  console.log(req.body)
  switch (req.body.keyword) {
  case 'CLUE1':
    keyword = 'clue1.ogg'
    break;
  case 'CLUE2':
    keyword = 'clue2.ogg'
    break;
  }
});

Em seguida, ainda dentro da /smsInbound roteiro, conecte-se à Voice API da Nexmo com nexmo.calls.create() o que, em seguida, chamará a /playRecording rota e a função para transmitir a pista correta. E, por fim, chame a função se a resposta for 200.

// server.js
nexmo.calls.create({
  to: [{
    type: 'phone',
    number: req.body.msisdn
  }],
  from: {
    type: 'phone',
    number: process.env.NEXMO_NUMBER
  },
  answer_url: [`${req.protocol}://${req.headers.host}/playRecording/${keyword}`]
});
res.status(200).send();

Gerar códigos QR

Em seguida, no seu index.html arquivo, vamos criar os códigos QR. Usei o CDN do qrcode-generator para gerar códigos dinamicamente com base na quantidade de pistas. É assim que <body /> é a aparência do meu index.html :

<!-- index.html -->
<body>
  <header>
    <h1>
      Scavenger Hunt
    </h1>
    <h3>
      with Nexmo SMS & Voice APIs and QR Codes
    </h3>
  </header>

  <main>
    <div id="placeHolder"></div>
  </main>

  <footer>
  </footer>

  <script src="https://cdnjs.cloudflare.com/ajax/libs/qrcode-generator/1.4.3/qrcode.min.js" integrity="sha256-zJI7J3Bt9A8QR4/b9OIKXFw25pp2rpoQBQXUVLrdYL8=" crossorigin="anonymous"></script>
  <script>

    const codes = ['clue1', 'clue2'];
    const YOUR_NEXMO_NUMBER = 18001234567
 
    const createQRCode = (data) => {
      let typeNumber = 4;
      let errorCorrectionLevel = 'L';
      let qr = qrcode(typeNumber, errorCorrectionLevel);

      qr.addData(data);
      qr.make();

      return qr.createImgTag(4,40);
    }

    codes.map((code) => {
      let elementNode = document.getElementById('placeHolder');
      let image = createQRCode(`SMSTO:${YOUR_NEXMO_NUMBER}:${code}`);
      let clueCount = "clue " + code.substr(-1);
      elementNode.append(clueCount);
      elementNode.appendChild(document.createRange().createContextualFragment(image));
    });

  </script>

</body>

Certifique-se de substituir YOUR_NEXMO_NUMBER na createQRCode() função pelo seu número Nexmo para o qual você envia o SMS.

A última coisa que precisamos fazer é criar um assets.js arquivo e preenchê-lo com a lógica necessária para lidar com os recursos e as pistas do Glitch, para que possamos usar o CDN.

// assets.js
var express = require('express');
var fs = require('fs');

var router = express.Router();
var content = fs.readFileSync('.glitch-assets', 'utf8');
var rows = content.split("\n");
var assets = rows.map((row) => {
  try {
    return JSON.parse(row);
  } catch (e) {}
});
assets = assets.filter((asset) => asset);


router.use((request, response) => {
  response.header("Access-Control-Allow-Origin", "*");
  response.header("Access-Control-Allow-Methods", "GET");
  response.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Authorization");

  var path = request.path.substring(1);

  var [matching] = assets.filter((asset) => {
    if(asset.name)
      return asset.name.replace(/ /g,'%20') === path;
  });

  if (!matching || !matching.url) {
    return response.status(404).end("No such file");
  }

  return response.redirect(matching.url);
});

module.exports = router;

qr codes

Boa caçada! 🕵🏼‍

Parabéns! Conseguimos gerar códigos QR com sucesso na interface da nossa página da web. Você pode pegá-los e colocá-los nos locais correspondentes às pistas espalhados pela sua cidade ou bairro!

Assim que um participante da caça ao tesouro encontrar uma pista específica, ele deverá poder escaneá-la com seu smartphone, e uma mensagem de texto pré-preenchida estará pronta para ser enviada ao seu número de telefone Nexmo. Assim que essa mensagem SMS for enviada com sucesso, o participante receberá uma ligação desse mesmo número com a gravação de áudio da próxima pista. A caça pode então continuar!