Documentation

Powered by Algolia

Visual state

The client application can communicate with voice scripts by sending arbitrary JSON objects at any time. These JSON objects are available in the runtime variable p.visual. This visual state will be different and independent for each user of your app. Visual state is the session-specific object and therefore it will not persist between sessions.

The client application sends this visual state object by calling setVisualState() method from Alan SDK. For example:

alanBtnInstance.setVisualState({data: "your data"});

Using visual state to differ command logic

Visual state informs the voice script about the current application state (What screen is the user viewing now, what data is available in the current visual context, what element is selected and so on). This information can be used to build a relevant voice response and synchronise application with script execution. Let's assume that your app sends JSON {"screen": "Products"} when user opens products screen and {"screen": "Checkout"} for checkout screen. Now we can differ Alan response depending on the visual state received from the app.

intent("what is this", "what screen I'm viewing", p => {
    let screen = p.visual.screen;
    switch (screen) {
        case "Products":
            p.play("This is the Products screen");
            break;
        case "Checkout":
            p.play("This is the Checkout screen");
            break;
        default:
            p.play("(Sorry,|) I have no data about this screen");
    }
});

Using visual state to activate commands

Visual states can also be used as conditional filters for user-given commands. For this you need to use visual() function, where you need to define either a JSON that should be matched or a filter. Let's use the same JSON received from the app ({"screen": "Products"} or {"screen": "Checkout"}).

const vProductsScreen = visual(state => state.screen === "Products");
const vCheckoutScreen = visual({"screen": "Checkout"});

intent(vProductsScreen, 'what is this', p => {
    p.play('This is the Products screen');
});

intent(vCheckoutScreen, 'what is this', p => {
    p.play('This is the Checkout screen');
});

Now depending on the JSON received from the app only one of this intents will be active and matched at a time. Even when they have the same patterns.

As you develop your app you might find that there is too many commands that are using the same visual state. And such commands might be scattered across the script. In this case we allow to group commands under the same visual filter, this will greatly increase readability of the script should you need to do some changes in it.

const vProductsScreen = visual(state => state.screen === "Products");
const vCheckoutScreen = visual({"screen": "Checkout"});

vProductsScreen(() => {
    intent('what is this', p => {
        p.play('This is the Products screen');
    });
    
    intent('what can I do here', p => {
        p.play('On this screen you can choose the products that you want to order');
    });
});

vCheckoutScreen(() => {
    intent('what is this', p => {
        p.play('This is the Checkout screen');
    });
    
    intent('what can I do here', p => {
        p.play('On this screen you can finish your order or remove some of the unwanted products');
    });
});