iOS Guides

Customizing Help Prompts

On some head units it is possible to display a customized help menu or speak a custom command if the user asks for help while using your app. The help menu is commonly used to let users know what voice commands are available, however, it can also be customized to help your user navigate the app or let them know what features are available.

You can customize the help menu with your own title and/or menu options. If you don't customize these options, then the head unit's default menu will be used.

If you wish to use an image, you should check the sdlManager.systemCapabilityManager.defaultMainWindowCapability.imageFields for an imageField.name of vrHelpItem to see if that image is supported. If vrHelpItem is in the imageFields array, then it can be used. You will then need to upload the image using the file manager before using it in the request. See the Uploading Images section for more information.

Objc

SDLSetGlobalProperties *setGlobals = [[SDLSetGlobalProperties alloc] init];
setGlobals.vrHelpTitle = <#Custom help title string such as: "What Can I Say?"#>;

// Set up the menu items
SDLVRHelpItem *item1 = [[SDLVRHelpItem alloc] initWithText:<#Help item name such as "Show Artists"#> image: <#A previously uploaded image or nil#> position: 1];
SDLVRHelpItem *item2 = [[SDLVRHelpItem alloc] initWithText:<#Help item name such as "Shuffle All"#> image: <#A previously uploaded image or nil#> position: 2];
setGlobals.vrHelp = @[item1, item2];

[self.sdlManager sendRequest:setGlobals withResponseHandler:^(SDLRPCRequest *request, SDLRPCResponse *response, NSError *error) {
    if (error != nil) {
        // Something went wrong
        return;
    }

    // The help menu is updated
}];

Swift

let setGlobals = SDLSetGlobalProperties()
setGlobals.vrHelpTitle = <#Custom help title string such as: "What Can I Say?"#>

// Set up the menu items
let item1 = SDLVRHelpItem(text:<#Help item name such as "Show Artists"#>, image: <#A previously uploaded image or nil#>, position: 1)
let item2 = SDLVRHelpItem(text:<#Help item name such as "Shuffle All"#>, image: <#A previously uploaded image or nil#>, position: 2)
setGlobals.vrHelp = [item1, item2];

sdlManager.send(request: setGlobals) { (request, response, error) in
    if let error = error {
        // Something went wrong
        return;
    }

    // The help menu is updated
}

Configuring the Help Prompt

On head units that support voice recognition, a user can request assistance by saying "Help." In addition to displaying the help menu discussed above a custom spoken text-to-speech response can be spoken to the user.

Objc

SDLSetGlobalProperties *setGlobals = [[SDLSetGlobalProperties alloc] init];
setGlobals.helpPrompt = [SDLTTSChunk textChunksFromString:<#Your custom help prompt#>];

[self.sdlManager sendRequest:setGlobals withResponseHandler:^(SDLRPCRequest *request, SDLRPCResponse *response, NSError *error) {
    if (error != nil) {
        // Something went wrong
        return;
    }

    // The help prompt is updated
}];

Swift

let setGlobals = SDLSetGlobalProperties()
setGlobals.helpPrompt = SDLTTSChunk.textChunks(from: <#Your custom help prompt#>)

sdlManager.send(request: setGlobals) { (request, response, error) in
    if let error = error {
        // Something went wrong
        return
    }

    // The help prompt is updated
}

Configuring the Timeout Prompt

If you display any sort of popup menu or modal interaction that has a timeout – such as an alert, interaction, or slider – you can create a custom text-to-speech response that will be spoken to the user in the event that a timeout occurs.

Objc

SDLSetGlobalProperties *setGlobals = [[SDLSetGlobalProperties alloc] init];
setGlobals.timeoutPrompt = [SDLTTSChunk textChunksFromString:<#Your custom help prompt#>];

[self.sdlManager sendRequest:setGlobals withResponseHandler:^(SDLRPCRequest *request, SDLRPCResponse *response, NSError *error) {
    if (error != nil) {
        // Something went wrong
    }

    // The timeout prompt is updated
}];

Swift

let setGlobals = SDLSetGlobalProperties()
setGlobals.timeoutPrompt = SDLTTSChunk.textChunks(from: <#Your custom help prompt#>)

sdlManager.send(request: setGlobals) { (request, response, error) in
    if let error = error {
        // Something went wrong
    }

    // The timeout prompt is updated
}

You can also reset your customizations to the help menu or spoken prompts. To do so, you will send a ResetGlobalProperties RPC with the fields that you wish to clear.

Objc

// Reset the help menu
SDLResetGlobalProperties *resetGlobals = [[SDLResetGlobalProperties alloc] initWithProperties:@[SDLGlobalPropertyVoiceRecognitionHelpItems, SDLGlobalPropertyVoiceRecognitionHelpTitle]];

// Reset the menu icon and title
SDLResetGlobalProperties *resetGlobals = [[SDLResetGlobalProperties alloc] initWithProperties:@[SDLGlobalPropertyMenuIcon, SDLGlobalPropertyMenuName]];

// Reset the spoken prompts
SDLResetGlobalProperties *resetGlobals = [[SDLResetGlobalProperties alloc] initWithProperties:@[SDLGlobalPropertyHelpPrompt, SDLGlobalPropertyTimeoutPrompt]];

[self.sdlManager sendRequest:resetGlobals withResponseHandler:^(SDLRPCRequest *request, SDLRPCResponse *response, NSError *error) {
    if (error != nil) {
        // Something went wrong
    }

    // The global properties are reset
}];

Swift

// Reset the help menu
let resetGlobals = SDLResetGlobalProperties(properties: [.voiceRecognitionHelpItems, .voiceRecognitionHelpTitle])

// Reset the menu icon and title
let resetGlobals = SDLResetGlobalProperties(properties: [.menuIcon, .menuName])

// Reset the spoken prompts
let resetGlobals = SDLResetGlobalProperties(properties: [.helpPrompt, .timeoutPrompt])
sdlManager.send(request: resetGlobals) { (request, response, error) in
    if let error = error {
        // Something went wrong
    }

    // The global properties are reset
}

View on GitHub.com

Previous Section Next Section

Customizing Help Prompts

Configuring the Help Menu

Configuring the Help Prompt

Configuring the Timeout Prompt

Clearing Help Menu and Prompt Customizations