Erstellen Sie eine interaktive Schnitzeljagd mit Nexmo SMS und Voice API

Einführung

QR-Codes sind heutzutage allgegenwärtig: auf der Rückseite von Visitenkarten, auf Flyern oder Plakatwänden - ganz egal. Sie machen Informationen für jeden, der ein Smartphone besitzt, schnell zugänglich und haben sich daher im letzten Jahrzehnt durchgesetzt.

Heute werden wir diese Funktionalität nutzen, um eine interaktive Schnitzeljagd in Ihrer Stadt zu erstellen!

🔎 Eine Schnitzeljagd-App 🔎

Ich dachte mir, was gibt es Besseres, als Freunde und Familie mit einer interaktiven Schnitzeljagd von der Couch zu holen und in die Nachbarschaft zu gehen? Und so dachte ich, dass es Spaß machen würde, etwas mit Nexmos Voice und SMS APIs zu entwerfen und zu bauen, um genau das zu tun. In diesem Tutorial geht es darum, wie man QR-Codes erstellt, die man in der Nachbarschaft versteckt, und wie man eine App mit Express und Node.js erstellt, die eine entsprechende SMS an eine Nexmo-Telefonnummer sendet, die den Spieler mit einem aufgezeichneten Hinweis zurückruft! Die Jagd kann mit so vielen Hinweisen fortgesetzt werden, wie Sie möchten.

Der Ablauf der App:

• Benutzer findet einen QR-Code

• Scannt den QR-Code mit seinem Smartphone

• SMS wird mit einem Hinweis versehen, der an eine Nexmo-Telefonnummer gesendet werden soll

• Benutzer drückt auf Senden

• App initialisiert einen Telefonanruf

• Aufnahme der Hinweisspiele

• Der Benutzer sucht nach dem neuen Hinweis und das Spiel geht weiter!

Voraussetzungen

Für diese Anleitung benötigen Sie einen Account bei Vonage. Sie können sich jetzt anmelden für kostenlos wenn Sie noch keinen Account haben.

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Wenn Sie jedoch zu einem funktionierenden Projekt übergehen möchten, können Sie die QR-Code-Leser-App sofort in Glitch nachbauen.

Ansonsten können Sie in wenigen Schritten Ihre eigenen Hinweise und Ihre eigene App von Grund auf neu erstellen!

Zeichnen Sie Ihre Schnitzeljagd-Hinweise auf

Nehmen Sie die Hinweise für Ihre Schnitzeljagd mit Ihrem bevorzugten Aufnahmegerät als .ogg-Dateien auf. Hier ist ein Beispiel für einen meiner Hinweise: [audio ogg="https://www.nexmo.com/wp-content/uploads/2019/08/clue1.ogg"]

(TIPP! er führt zum Fremont Troll unter einer Brücke hier in Seattle 😆)

troll

Nexmo Account erstellen

Wenn Sie es noch nicht getan haben, erstellen Sie einen kostenlosen Nexmo Account und als zusätzlichen Bonus werden Ihrem Account 2 Euro gutgeschrieben, damit Sie Ihre neue Anwendung nutzen können. Gehen Sie zu <${CUSTOMER_DASHBOARD_URL}/sign-up?icid=tryitfree_api-developer-adp_nexmodashbdfreetrialsignup_nav> und gehen Sie durch die Anmeldeschritte. Sobald Sie damit fertig sind, befinden Sie sich in Ihrem Nexmo Dashboard.

Kaufen Sie eine Nexmo-Telefonnummer

Klicken Sie auf dem Nexmo Dashboard auf den Menüpunkt Numbers Menüpunkt auf der linken Seite.

Klicken Sie auf die Option Buy Numbers und Sie werden auf eine Seite weitergeleitet, auf der Sie das Land, die Merkmale, den Typ und die vier Ziffern, die die Nummer haben soll, auswählen können.

buy number dashboard

Wählen Sie das Land, in dem Sie sich gerade befinden, damit der Anruf lokal erfolgt. Wählen Sie unter Funktionen Voice und für die Art des Anrufs entweder Handy oder Festnetz.

Klicken Sie auf Search um eine Liste der verfügbaren Telefonnummern anzuzeigen.

Wählen Sie eine Zahl aus, indem Sie auf die orangefarbene Buy klicken und dann erneut auf die orangefarbene Buy klicken, sobald Sie in der Bestätigungsaufforderung sind.

Sie besitzen nun eine Nexmo-Telefonnummer. Ihr nächster Schritt ist die Erstellung einer Anwendung im Nexmo Dashboard.

Erstellen einer Nexmo Voice Applikation

Klicken Sie im linken Menü auf den Menüpunkt Voice Menüpunkt.

Wählen Sie die Create an application Option. Sie werden zu einer Seite weitergeleitet, auf der Sie eine neue Nexmo-Anwendung einrichten können.

Füllen Sie das Formular mit den folgenden Angaben aus:

Application name Textfeld eingeben qr code scavenger hunt

Event URL Textfeld Ihre Glitch-URL ein: https://[your Glitch URL].glitch.me/events

Answer URL Textfeld erneut Ihre Glitch-URL ein: https://[your Glitch URL].glitch.me/answer

Wenn Sie alles eingegeben haben, klicken Sie auf die blaue Create Application Schaltfläche.

Stellen Sie sicher, dass Sie ein Schlüsselpaar aus öffentlichem und privatem Schlüssel erzeugen und es speichern.

Alles miteinander verbinden

Sie haben jetzt eine Nexmo-Nummer und eine Voice-Anwendung, die Sie nur noch miteinander verbinden müssen.

Wählen Sie die Option Numbers im linken Menü und klicken Sie dann auf Your numbers. Sie werden auf eine Seite weitergeleitet, auf der die soeben erworbene Telefonnummer aufgeführt ist.

Klicken Sie auf das Zahnrad-Symbol auf der rechten Seite der Seite und ein Menü erscheint. Geben Sie in das Feld Inbound Webhook URL Feld geben Sie Ihre Glitch-URL ein, gefolgt von /smsInbound: https://[Ihre Glitch-URL].glitch.me/smsInbound`

Wählen Sie Application unter dem Forward to Bereich

Wählen Sie Ihre neue Anwendung aus der Dropdown-Liste unter dem Application Bereich. Drücken Sie die blaue Ok Taste

inbound webhook

Ihre neue Nexmo-Sprachnummer ist nun mit Ihrer neuen Nexmo-Anwendung verknüpft, und mit diesem letzten Schritt sind Sie bereit, Ihre Anwendung zu erstellen!

Fehlersuche

Wählen Sie auf dem Nexmo-Dashboard unter Ihrem Namen und den Account-Einstellungen POST-JSON als Ihre Standard-HTTP-METHODE auswählen:

post json

Erste Schritte auf Glitch

Um zu beginnen, erstellen Sie ein neues Projekt in Glitch und wählen Sie die hello-express Vorlage.

In der package.json Datei wählen Sie das Add a package um nach den folgenden Abhängigkeiten zu suchen und diese hinzuzufügen: nexmo, qrcode, body-parser, und dotenv.

dependency list

Am Anfang Ihrer server.js Datei richten wir unseren Express-Server ein, benötigen unsere Abhängigkeiten und binden unsere Nexmo-Anmeldedaten ein:

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

In der Datei .env Datei geben Sie die Nexmo-spezifischen Anmeldedaten ein, die wir gerade im Nexmo-Dashboard erstellt haben:

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

Ersetzen Sie den API-Schlüssel, das API-Geheimnis, die App-ID und Ihre Nexmo Number. Um den privaten Schlüssel hinzuzufügen, wählen Sie den New File Toggle in der oberen linken Ecke und nennen Sie ihn .data/private.key. Fügen Sie in diese Datei den privaten Schlüssel ein, den Sie bei der Erstellung Ihrer Voice-Anwendung erzeugt haben. Diese Datei wird in Glitch unsichtbar, wenn Sie Ihren Code aus Sicherheitsgründen neu mischen.

Routen erstellen inserver.js

Als Nächstes erstellen wir unter diesen Anmeldeinformationen zusätzlich zu unserer Standardroute und dem Listener einige andere Routen:

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

Die ersten Funktionen, die wir ausfüllen müssen, sind für /events und /answer die beide mit der send() Funktionalität antworten, wenn die Statusantwort 200 lautet:

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

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

Dann für die /playRecording Route die App dynamisch anweisen, die Aufnahmen Ihrer Schnitzeljagd-Hinweise abzuspielen:

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

Und schließlich erstellen Sie für die /smsInbound Route eine Switch-Anweisung, die den gefundenen Hinweis verarbeitet. Ihr könnt sie benennen, wie ihr wollt (ich würde empfehlen, etwas kreativer zu sein als meine langweiligen numerischen Namen 😂).

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

Dann, immer noch innerhalb der /smsInbound Route, eine Verbindung zur Nexmo Voice API mit nexmo.calls.create() die dann die /playRecording Route und die Funktion aufruft, um den richtigen Hinweis zu streamen. Und schließlich senden Sie die Funktion, wenn die Antwort lautet 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();

QR-Codes generieren

Als nächstes erstellen wir in Ihrer index.html Datei die QR-Codes erstellt. Ich habe den qrcode-generator CDN um die Codes dynamisch auf der Grundlage der Anzahl der Hinweise zu generieren. Dies ist die <body /> meiner index.html sieht so aus:

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

Stellen Sie sicher, dass Sie IHRE_NEXMO_NUMMER in der Funktion createQRCode() Funktion durch Ihre Nexmo-Nummer, an die Sie die SMS senden.

Das letzte, was wir tun müssen, ist eine assets.js Datei zu erstellen und sie mit Logik zu füllen, um die Assets und Hinweise von Glitch zu behandeln, damit wir das CDN nutzen können.

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

Frohes Jagen! 🕵🏼‍

Herzlichen Glückwunsch! Wir haben erfolgreich QR-Codes auf der Vorderseite unserer Webseite generiert. Sie können diese nehmen und sie an den entsprechenden Hinweisen in Ihrer Stadt oder Nachbarschaft anbringen!

Sobald ein Schnitzeljäger einen bestimmten Hinweis gefunden hat, sollte er ihn mit seinem Smartphone einscannen können, woraufhin eine vorbereitete Textnachricht an Ihre Nexmo-Telefonnummer gesendet werden kann. Sobald diese SMS erfolgreich gesendet wurde, erhält der Schnitzeljäger einen Anruf von derselben Nummer mit der Audioaufnahme des nächsten Hinweises. Die Jagd kann dann weitergehen!