Créez une chasse au trésor interactive avec Nexmo SMS et Voice API

Introduction

Les codes QR sont aujourd'hui omniprésents : au dos des cartes de visite, sur les prospectus ou les panneaux d'affichage, etc. Ils rendent l'information rapidement accessible à toute personne équipée d'un smartphone et se sont donc popularisés au cours de la dernière décennie.

Aujourd'hui, nous allons capitaliser sur cette fonctionnalité pour créer une chasse au trésor interactive à travers votre ville !

🔎 Une application de chasse au trésor 🔎

Je me suis dit qu'il n'y avait pas de meilleur moyen d'inciter vos amis et votre famille à sortir du canapé et à se rendre dans le quartier qu'avec une chasse au trésor interactive. J'ai donc pensé qu'il serait amusant de concevoir et de construire quelque chose avec les API Voice et SMS de Nexmo pour faire exactement cela. Ce tutoriel explique comment créer des Numbers à cacher dans votre quartier et comment créer une application avec Express et Node.js pour remplir un SMS correspondant à envoyer à un numéro de téléphone Nexmo qui rappellera le joueur avec un indice enregistré ! La chasse peut se poursuivre jusqu'au nombre d'indices que VOUS choisissez.

Le flux de l'application :

• L'utilisateur trouve un code QR

• Scanne le code QR avec son smartphone

• Le SMS est pré-rempli avec un indice à envoyer à un numéro de téléphone de Numbers.

• L'utilisateur appuie sur envoyer

• L'application initialise un appel téléphonique

• Enregistrement des jeux d'indices

• L'utilisateur recherche ce nouvel indice et le jeu continue !

Conditions préalables

Pour suivre ce tutoriel, vous aurez besoin d'un Account Vonage. Vous pouvez vous inscrire dès maintenant pour gratuitement si vous n'avez pas encore de compte.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Mais si vous voulez passer à un projet fonctionnel, vous pouvez remixer l'application QR Code Reader App immédiatement dans Glitch.

Sinon, en quelques étapes seulement, vous pouvez créer vos propres indices et applications à partir de zéro !

Enregistrer les indices de la chasse au trésor

À l'aide de l'appareil d'enregistrement de votre choix, enregistrez les indices de votre chasse au trésor sous forme de fichiers .ogg. Voici un exemple d'un de mes indices : [audio ogg="https://www.nexmo.com/wp-content/uploads/2019/08/clue1.ogg"]

(INDICE : il mène au Fremont Troll sous un pont ici à Seattle 😆)

troll

Créer un Account Nexmo

Si vous ne l'avez pas encore fait, créez un compte Nexmo gratuitement, et en prime, votre compte sera crédité de 2 euros pour commencer à utiliser votre nouvelle application. Rendez-vous sur <${CUSTOMER_DASHBOARD_URL}/sign-up?icid=tryitfree_api-developer-adp_nexmodashbdfreetrialsignup_nav> et suivez les étapes de l'inscription. Une fois que vous aurez terminé, vous serez dans votre tableau de bord Nexmo.

Acheter un numéro de téléphone Nexmo

Dans le tableau de bord Nexmo, cliquez sur l'élément de menu Numbers dans le menu de gauche.

Cliquez sur l'option Buy Numbers et vous serez dirigé vers une page où vous pourrez choisir un pays, des caractéristiques, un type et les quatre chiffres que vous souhaitez voir figurer sur le numéro.

buy number dashboard

Sélectionnez le pays dans lequel vous vous trouvez pour que l'appel soit local. Pour les fonctions, sélectionnez Voice et pour le type, mobile ou fixe fonctionnera parfaitement.

Cliquez sur Search pour afficher la liste des numéros de téléphone disponibles.

Sélectionnez un numéro en cliquant sur le bouton orange Buy et en cliquant à nouveau sur le bouton orange Buy une fois que vous êtes dans la fenêtre de confirmation.

Vous possédez maintenant un numéro de téléphone Nexmo. La prochaine étape consiste à créer une application dans le tableau de bord Nexmo.

Créer une application Nexmo Voice

Dans le menu de gauche, cliquez sur l'élément de menu Voice dans le menu.

Sélectionnez l'option Create an application option. Vous êtes dirigé vers une page où vous pouvez créer une nouvelle application Nexmo.

Complétez le formulaire avec les informations suivantes :

Application name champ de texte entrer qr code scavenger hunt

Event URL entrez votre URL Glitch : https://[your Glitch URL].glitch.me/events

Answer URL saisissez à nouveau l'URL de votre Glitch dans le champ de texte : https://[your Glitch URL].glitch.me/answer

Une fois que tout est en place, cliquez sur le bouton bleu Create Application bleu.

Veillez à générer une paire de clés publique/privée et à la sauvegarder.

Lier le tout

Vous disposez désormais d'un numéro Numbers et d'une application Voice, il ne vous reste plus qu'à relier les deux.

Sélectionnez l'option Numbers dans le menu de gauche, puis cliquez sur Your numbers. Vous serez dirigé vers une page répertoriant le numéro de téléphone que vous venez d'acheter.

Cliquez sur l'icône de l'engrenage à droite de la page et un menu s'affichera. Dans le champ Inbound Webhook URL entrez votre URL Glitch suivie de /smsInbound: https://[votre URL Glitch].glitch.me/smsInbound`

Sélectionnez Application sous la zone Forward to zone

Sélectionnez votre nouvelle application dans la liste déroulante située sous la rubrique Application de la zone. Appuyez sur le bouton bleu Ok bleu

inbound webhook

Votre nouveau numéro de voix Nexmo est maintenant lié à votre nouvelle application Nexmo, et avec cette dernière étape, vous êtes prêt à créer votre application !

Dépannage

Sur le tableau de bord Nexmo, sous votre nom et les paramètres de votre Account, assurez-vous de sélectionner POST-JSON comme MÉTHODE HTTP par défaut :

post json

Débuter sur Glitch

Pour commencer, créez un nouveau projet sur Glitch, en choisissant le modèle hello-express modèle.

Dans le package.json sélectionnez le menu déroulant Add a package pour rechercher et ajouter les dépendances suivantes : nexmo, qrcode, body-parser, et dotenv.

dependency list

Au début de votre fichier server.js configurons notre serveur Express, exigeons nos dépendances et intégrons nos identifiants 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}`
  });

Dans le fichier .env remplissez les informations d'identification spécifiques à Nexmo que nous venons de créer dans le Nexmo Dashboard :

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

Remplacez la clé API, le secret API, l'identifiant de l'application et votre Numbers Nexmo. Pour inclure la clé privée, sélectionnez l'option New File dans le coin supérieur gauche et nommez-la .data/private.key. Dans ce fichier, collez la clé privée que vous avez générée lorsque vous avez créé votre application vocale. Ce fichier deviendra invisible dans Glitch si vous remixez votre code pour des raisons de sécurité.

Créer des itinéraires dansserver.js

Ensuite, sous ces informations d'identification, en plus de notre route par défaut et de l'auditeur, créons quelques routes différentes :

// 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);
});

Les premières fonctions que nous devons remplir sont pour /events et /answer qui répondront toutes deux avec la fonctionnalité send() si la réponse du statut est 200 :

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

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

Ensuite, pour l'itinéraire /playRecording vous demanderez à l'application de jouer les enregistrements des indices de votre chasse au trésor :

// 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);
});

Enfin, pour l'itinéraire /smsInbound créez une instruction switch qui gérera l'indice trouvé. Vous pouvez les nommer comme vous le souhaitez (je vous recommande d'être un peu plus créatif que mes noms numériques ennuyeux 😂).

// 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;
  }
});

Ensuite, toujours dans l'itinéraire /smsInbound se connecter à l'API Voice de Nexmo avec nexmo.calls.create() qui appellera alors la route et la fonction /playRecording et la fonction pour transmettre le bon indice. Enfin, envoyez la fonction si la réponse est 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();

Générer des codes QR

Ensuite, dans votre fichier index.html créons les QR Codes. J'ai utilisé le CDN qrcode-generator CDN pour générer dynamiquement les codes en fonction du nombre d'indices. C'est ce que le <body /> de mon index.html ressemble :

<!-- 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>

Veillez à remplacer YOUR_NEXMO_NUMBER dans la fonction createQRCode() par le numéro Nexmo auquel vous envoyez le SMS.

La dernière chose à faire est de créer un fichier assets.js et le remplir avec de la logique pour gérer les actifs et les indices de Glitch afin que nous puissions utiliser le 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

Bonne chasse ! 🕵🏼‍

Félicitations ! Nous avons réussi à générer des codes QR sur la page d'accueil de notre site web. Vous pouvez prendre ces codes et les placer à l'endroit correspondant à l'indice dans votre ville ou votre quartier !

Lorsqu'un chasseur de trésors trouve un indice particulier, il devrait pouvoir le scanner avec son smartphone et un message texte prérempli sera préparé et prêt à être envoyé à votre numéro de téléphone Numbers. Une fois le SMS envoyé avec succès, le chasseur de trésors recevra un appel téléphonique de ce même numéro avec l'enregistrement audio de l'indice suivant. La chasse peut alors continuer !