Een Alexa-skill maken met PHP – tutorial
· door Daniel
Sinds mijn vorige tutorial is er het een en ander veranderd op het Alexa Developer-platform van Amazon. De interface is vernieuwd en in plaats van het oude systeem, waarin intents handmatig moesten worden aangemaakt, is er nu een skill builder.
Daarom geef ik je hier een kleine update van mijn oude Alexa-PHP-tutorials.Het skilloverzicht
Laten we beginnen. Ik ga ervan uit dat je een Alexa Developer-account hebt en spring dus meteen naar het nieuwe dashboard. Via het menu-item ‘Your Alexa Consoles’ (rechtsboven) > Skills kom je bij je skilloverzicht.
Naar je Alexa-skilloverzichtEen skill maken
Onder ‘Create Skill’ kunnen we onze eerste eigen Amazon Alexa-skill maken. Nadat je op de knop hebt geklikt, geef je in de eerste stap een naam aan de skill. In mijn voorbeeld: Daniel.
Daarna kiezen we het model voor de skill. We willen klein beginnen en niet meteen een smarthome- of videoskill bouwen. Daarom kiezen we hier Custom.
Skillinstellingen
Skilldashboard
Dat was het: nu kom je in het dashboard van je skill. In de bovenste balk vind je de volgende punten:
- Daniel => naam van je skill
- Build => hier maken we de commando’s
- Test => zodat we de functies later kunnen controleren
- Launch => als je je skill in de Amazon Store wilt publiceren
- Measure => gebruiksgedrag enz.
Onder Build in de linkerzijbalk staat het belangrijkste: de aanroepen en instellingen van de skill.
Invocation name
In de rechterbalk vind je een handige checklist met taken. Daar beginnen we ook en we klikken op ‘1st Invocation Name’. De invocation name is de ‘startzin’ waarmee je je skill via Alexa aanspreekt, bijvoorbeeld ‘Alexa, vraag INVOCATION NAME’. Ik gebruik daniel als voorbeeld. Belangrijk: hoofdletters zijn hier niet toegestaan.
Een intent maken
Nadat we de invocation name hebben ingesteld, kunnen we de eerste intent van onze skill maken. Een intent is een commando dat op je server wordt uitgevoerd zodra een van de bijbehorende uitingen wordt herkend. Dat klinkt niet ingewikkeld. Hier een voorbeeld:
- Intent = hello
- Utterances
- hi
- hello
- moin
Als je nu ‘hi’ tegen je skill zegt, wordt de intent ‘hello’ op je server uitgevoerd. Wat die intent teruggeeft, hangt af van je programmering.
Utterances en slots van de skill
Oké, we hebben nu een intent ‘hello’ gemaakt. Nu maken we 3 utterances zoals hierboven beschreven: hello, hi en moin.
Ik wil ook dat er een slot (of variabele) naar mijn server wordt doorgegeven. Ik voeg een slot ‘name’ toe met het slottype ‘AMAZON.DE_FIRST_NAME’. Die moet ik natuurlijk met accolades aan de utterances toevoegen.
Onze eerste intent is nu klaar.
Een endpoint instellen
Nu kunnen we een endpoint instellen. Het endpoint is de bestemming waar de verzoeken van je skill naartoe worden gestuurd. In mijn geval is dat https://alexa.welaunch.io. Belangrijk is dat het endpoint een versleutelde verbinding (https) heeft.
Selecteer HTTPS, vul het adres in en kies ‘My development endpoint has a certificate from a trusted certificate authority’. Ga daarna terug naar het interactiemodel en klik op ‘Build’.
Het PHP-gedeelte
Nu komen we eindelijk bij PHP. Vergeleken met mijn oude tutorial verandert hier eigenlijk niet veel, maar ik leg het nog even kort uit. Als logger gebruik ik Monolog om te controleren waarom sommige vragen niet zijn beantwoord. Je ziet ook welke intents of utterances worden gevraagd maar niet door je skill worden ondersteund. Als ik bijvoorbeeld ‘hiderido’ zeg, ontbreekt die utterance.
Composer-bestand voor Monolog:
{
"name": "db-dzine/alexaphp",
"description": "PHP Class for Alexa",
"type": "library",
"authors": ,
"minimum-stability": "dev",
"require": {
"monolog/monolog": "1.x-dev",
}
}
Voer daarna composer install uit in je map. Vervolgens kun je een index.php maken en autoload en Monolog laden:
<?php // Load Monolog Vendor require_once __DIR__ . '/vendor/autoload.php'; // Autoload files using Composer autoload use Monolog\Logger; use Monolog\Handler\StreamHandler; // Save Requests on debug log define('DEBUG', true); define('DEBUG_FILE', __DIR__ . '/logs/log.log'); $logger = new Logger('Alexa'); $logger->pushHandler( new StreamHandler( DEBUG_FILE, Logger::INFO ) );
Om verzoeken van je skill op te vangen:
// Get Alexa Request
$jsonRequest = file_get_contents('php://input');
// Decode the Request
$data = json_decode($jsonRequest, true);
// Abort when Empty
if( empty($data) || (!isset($data) ) ) {
die('Bad Request');
}
De volgende variabelen kun je uit de data-array lezen. Er staat natuurlijk meer in, maar dit zijn de belangrijkste:
$intent = !empty($data) ? $data : 'default'; $intentData = !empty($data) ? $data : 'default'; $sessionId = !empty($data) ? $data : 'default'; $logger->info( var_export($data, true)); $logger->info( $intentData ); $logger->info( $sessionId);
Nu kunnen we met de variabele $intent achterhalen welke intent is aangesproken. Met een switch-statement geef ik bij de intent ‘hello’ een vriendelijke begroeting terug. En als er een naam is meegegeven, geef ik die ook terug. Het geheel gaat als JSON-gecodeerde string terug naar Alexa.
switch ($intent) {
// Hallo Intent für Utterances hi, hallo, moin
case 'hallo':
// Hallo Intentdata abfragen
$name = !empty($intentData) ? $intentData : '';
// save $name in data file - here also mysql can be used
// later you can use session id to get data like name
if(!empty($name)) {
$dataToSave = array($sessionId => array(
'name' => $name
));
$fp = fopen('data.json', 'w');
fwrite($fp, json_encode($dataToSave));
fclose($fp);
}
$responseArray = ,
'shouldEndSession' => false
]
];
break;
// Default
default:
$responseArray = ,
'shouldEndSession' => true
]
];
break;
}
header ( 'Content-Type: application/json' );
echo json_encode ( $responseArray );
die();
De skill testen
We kunnen onze skill testen met ‘Question daniel hello klaus’. Klinkt vreemd, maar ‘ask daniel’ start de skill (invocation name) en ‘hello’ (de intent) wordt uitgevoerd.
Je kunt ook de Alexa-app op je smartphone gebruiken om de skill te testen.