Commands: your plugin owns a phrase

A plugin can claim spoken phrases. Say one, and your plugin runs and does the work: no opening it, no tapping.

{
  "intents": ["heading to the office", "off to the office"],
  "permissions": ["open", "voice"],
  "minAppBuild": 26
}

hairobo.on('command', (c) => {          // c.text, c.phrase
  hairobo.voice.speak('Getting you a cab to the office.');
  hairobo.open.cab('office').then(() => hairobo.command.done());
});

That is the whole feature. cab/ in this kit is the working example.

Where your phrase sits

Every one of the app's own commands is tried first. Yours is tried after them and before the assistant. You can add what the app cannot do; you can never take away what it can. "What's the weather" stays the app's, whatever you claim.

Between plugins, the longest phrase wins, and a tie is broken the same way on every device rather than by who installed first. A suspended plugin claims nothing.

The rules for a phrase

At most 8 per plugin.
At least 6 characters, letters, numbers, spaces and apostrophes only.
Claim whole phrases people say, not words. A plugin claiming "cab" or "play" swallows half the app's own commands the moment it is installed, and the user has no way to see why the robot stopped understanding them. Review will refuse it.

Your phrase is matched anywhere in what was said, lowercased, so "right, I am heading to the office now" matches "heading to the office".

Phrases the app already owns

This is the mistake to avoid, and it is a quiet one.

The app answers "book a cab to the office" itself. If you claim that phrase, your plugin is installed, the phrase looks claimed, and it never runs. The app books the cab, the user sees something happen, and nothing anywhere says your plugin was skipped. It looks like your plugin is broken.

The example in this kit claims "heading to the office" for exactly that reason. The app has no answer for it, so the phrase is really yours. The plugin still ends up opening a cab, because that part is the app's job either way.

So claim the phrase the app does NOT have. Before you publish, say your phrases to a robot with your plugin uninstalled: anything that already works is not yours to take.

Written out in Config.swift terms, the app's own travel commands cover "book a cab", "get me a ride", "cab to", "uber to", "navigate to", "take me to", "directions to" and their obvious relatives. That list is not the whole app, which is the point of testing rather than reading.

How your plugin runs

With no screen. It is started when the phrase is heard, receives the command event, does its work, and stops when you call hairobo.command.done(). If you never call it, the app stops you after 25 seconds. There is nothing to draw and nobody to look at it: do the work, say something, finish.

Everything you already have works here: voice.speak, storage.*, assistant.ask, data.weather, and the rest, subject to the permissions you declared.

The user is told it is you. While your plugin is answering, the app shows your plugin's name on the robot's face. You cannot draw it, hide it or change it. A plugin speaking in the robot's own voice without the user knowing which is which would be the whole trust problem in one feature, so the app answers it rather than asking you to.

Doing things: ask, do not reach

await hairobo.open.cab('office');   // needs "open"

You name a place. The app resolves it, finds the pickup point and opens the cab app. You never see the address, the coordinates, or which cab app they use.

There is deliberately no "open this link". A plugin has no network, and a link you chose would be the way around that: anything you know could be put in the URL and read by whoever opens it. So the list of things you can open grows as whole actions, one at a time, and each one is the app doing the job on your behalf.

Today that list is: a cab to a place. More will follow the same shape.

open.cab resolves false if you call it more than once every few seconds: opening another app takes the screen away from the user, and a loop of that is unusable.

Saving a preference

Your own store, as always, and it needs no permission:

await hairobo.storage.set('destination', 'office');

That is how a plugin remembers "the office" without the app knowing what your plugin means by it.

Try it

cab/ in this kit is the example, and it also ships inside the app. Say "heading to the office" and watch the cab app open with the destination set. Save a place called "office" in the app first, under Your stuff.

Say "book a cab to the office" instead and the cab still opens, but the app did it and your plugin never ran. That is the difference worth seeing once.