Skip to main content
Samsung Developer Program

Controlling the RN Action Section

Rich notifications can specify one or more user actions to do something on the Android™ or Gear device. Each rich notification can have one or more actions associated with it, by specifying the actions in the rich notification's action array list or by adding them individually. The first action declared in the list section, or the first action added individually, is the primary action—the action most likely to be taken by the user.

The primary action UI button is available to the user in the primary section and in the More Options screen. All other actions in the list are secondary actions; their UI buttons are displayed in the More Options screen (after the primary action UI button in their declared or added order).

Rich Notification supports the following types of actions:

Host Action

The action is executed and managed by the specified Android app on the Android device via Android intents.

Remote Launch Action

The action is executed and managed by the specified Tizen™ app on the Gear device.

Remote Built-In Action

The action is executed and managed by the associated utility app on the Gear device:

CALL

SMS

Place a phone call from the Gear device.

Send an SMS message from the Gear device.

Remote Input Action

The user is prompted to provide additional input:

KEYBOARD

SINGLE_SELECT

MULTI_SELECT

The user can enter text using the specified device keyboard.

The user can choose 0 or 1 selection from a list.

The user can choose 0, 1, more selections from a list.    

Getting the user input is managed by the Gear device. Executing the action is handled by the specified Android app on the Android device via an Android intent.

The user's entry can be retrieved from the Android intent’s extras with the key: SAMSUNG_REMOTE_INPUT_RESULT.

Note: For single- and multi-selections, it is possible to display either: the text of each choice or the icon and text of each choice.  To display the icon and text of a choice, then ALL choices must specify their icon and text.  Every choice item must have an icon to be displayed on the wearable device. If some of the items omit icons or set as null, all icons of all choice items will not be displayed.

A SelectInputMode must have a choice at the list.

Your Android app:

  • Must construct each rich notification action object, either individually or in a list
  • Must specify aspects of each rich notification action
  • Must declare each rich notification action callback intent
  • Must add the actions after creating the rich notification (see Controlling Fundamental RN Elements and Aspects)

Rich Notification Action Section and More Options UI Screen Elements

SrnAction

setCallbackIntent()

Specifies the callback intent to be triggered when the user initiates the action

callbackIntent

Name of the intent                                                            

The intent must specify the callback action specific to the type of action (see SrnAction.CallbackIntent below).

SrnAction.CallbackIntent

getActivityCallback()

Creates a callback intent object that will start a new activity

intent

Name of the intent for launching the activity

Returns:

New CallbackIntent.

getBroadcastCallback()

Creates a callback intent object that will perform a broadcast

intent

Name of the intent for sending the broadcast

Returns:

New CallbackIntent.

getActivityCallback()

Creates a callback intent object that will start a new service

intent

Name of the intent for starting the service

Returns:

New CallbackIntent.

To specify a list of rich notification actions:

public List<SrnAction> actionList() {
    ArrayList<SrnAction> myActions = new ArrayList<SrnAction>();

    SrnHostAction primaryAction = new SrnHostAction("Read On Phone");
    Bitmap primaryActionBitmap = BitmapFactory.decodeResource(mContext.getResources(),
                                                                R.drawable.microphone_icon);
    SrnImageAsset primaryActionIcon = new SrnImageAsset(mContext,
                                               "primary_action_icon", primaryActionBitmap);

    Intent resultIntent = new Intent(mContext, MyCallbackActivity.class);
    resultIntent.setData(Uri.parse("http://readnwrite/authorericread_book_flyingmystery
                                                            and magic.html#.U-Cj3WPzkjY"));

    primaryAction.setIcon(primaryActionIcon);
    primaryAction.setToast("Your can read it on your phone_icon!");
    primaryAction.setCallbackIntent(CallbackIntent.getActivityCallback(resultIntent));
    myActions.add(primaryAction);

    SrnRemoteInputAction keyRemoteInputAction = new SrnRemoteInputAction("Comment");

    KeyboardInputMode keyboardInputMode = InputModeFactory.createKeyboardInputMode();
    keyboardInputMode.setPrefillString("@name");
    keyboardInputMode.setCharacterLimit(140);
    keyboardInputMode.setKeyboardType(KeyboardType.NORMAL);

    keyRemoteInputAction.setRequestedInputMode(keyboardInputMode);

    Intent keyboardIntent = new Intent(mContext, RichNotificationActivity.class);
    keyRemoteInputAction.setCallbackIntent(CallbackIntent
                                                    .getActivityCallback(keyboardIntent));

    myActions.add(keyRemoteInputAction);

    return myActions;
}

Host Actions

Host actions are executed and managed by the specified Android app on the Android device via Android intents.

SrnHostAction

SrnHostAction

Creates an action object to be performed by the Android device

label

Name of the host action displayed in the UI

setIcon()

Specifies the icon image asset to be used in the host action UI buttons

icon

Name of the icon image asset

setToast()

Specifies the text line associated with the action to be briefly displayed after the user selects the action

toast

Text line to be briefly displayed

To specify a host action (as a primary action):

SrnHostAction primaryAction = new SrnHostAction("See Online Forecast");
Bitmap primaryActionBitmap = BitmapFactory.decodeResource(mContext.getResources(),
                                                  R.drawable.microphone_icon);
SrnImageAsset primaryActionIcon = new SrnImageAsset(mContext, "primary_action_icon", 
                                                                        primaryActionBitmap);

primaryAction.setIcon(primaryActionIcon);
primaryAction.setToast("Check your phone_icon!");

Intent resultIntent = new Intent(Intent.ACTION_VIEW);
resultIntent.setData(Uri.parse("http://www.weather.com"));

primaryAction.setCallbackIntent(CallbackIntent.getActivityCallback(resultIntent));

myActions.add(primaryAction);

Remote Launch Actions

Remote launch actions are executed and managed by a Tizen app on the Gear device

SrnRemoteLaunchAction

SrnRemoteLaunchAction(label)        

Creates a remote launch action object to be performed by the Gear device with the specified name

label

Name of the remote launch action displayed in the UI

SrnRemoteLaunchAction(label, data)     

Creates a remote launch action object to be performed by the Gear device with the specified name and URI data

label

data

Name of the remote launch action displayed in the UI.

URI of the data associated with the action

setData()

Specifies the URI of the data associated with the action

data

URI of the data associated with the action

CAUTION:   Do NOT specify setData() when specifying  SrnRemoteLaunchAction(label, data) to construct the action.  Doing so will replace the previous data.

Note: Do not specify setData() when SrnRemoteLaunchAction(label, data) constructs the action.

setExtras()

Specifies the extras of the action

extras

Name of the bundle with action extras

setIcon()

Declares the icon image asset used in the remote launch action UI buttons

icon

Name of the icon image asset

setMimeType()

Specifies the MIME type of the URI data associated with the action

type

MIME type of the action URI data

setOperation()

Specifies the name of the action's operation

operation

Name of the action's operation

setPackage()

Specifies the package name of the application to be launched on the remote device

packageName

Name of the action's package

To specify a remote launch action:

Note: A Gear S or Gear S2 device must be connected to the Android device.

SrnRemoteLaunchAction remoteLaunchAction = new SrnRemoteLaunchAction("Make a Phone Call");
remoteLaunchAction.setPackage("com.samsung.dialer");
Bitmap phoneIconBitmap = BitmapFactory.decodeResource(context.getResources(), 
                                                                        R.drawable.phone_icon);
SrnImageAsset phoneIcon = new SrnImageAsset(context, "phone_icon", phoneIconBitmap);
remoteLaunchAction.setIcon(phoneIcon);
Intent remoteLaunchIntentResult = new Intent(context, RichNotificationActivity.class);
remoteLaunchAction.setCallbackIntent(CallbackIntent
                                 .getActivityCallback(remoteLaunchIntentResult));
myActions.add(remoteLaunchAction);

Remote Built-In Actions

Remote built-in actions are executed and managed by the associated built-in app on the Gear device. These actions use a default icon defined on the Gear device.

SrnRemoteBuiltInAction

SrnRemoteBuiltInAction(label)

Creates a built-in action object to be performed by the Gear device with the specified name

label

Name of the built-in action displayed in the UI

SrnRemoteBuiltInAction
(label, opType) 

Creates a built-in action object to be performed by the Gear device with the specified name and built-in operation

label

opType

Name of the built-in action displayed in the UI

Operation enum type of the built-in action, for example:

 

OperationType.CALL — Make a phone call from the Gear device.

 

OperationType.SMS — Make an SMS text call from the Gear device.

setType()

Specifies the URI of the data associated with the action

opType

Operation enum type of the built-in action, for example:

OperationType.CALL — Make a phone call from the Gear device

OperationType.SMS — Make an SMS text call from the Gear device

​Note: Do not specify setType() when SrnRemoteBuiltInAction(label, opType) constructs the action.

setData()

Specifies the URI of the data associated with the action

uri

URI of data the action is associated with

 

SrnRemoteBuiltInAction.OperationType

valueOf()     

Returns the enum constant of the specified type

name

Name of the enum constant operation type (CALL or SMS)

The string must exactly match the identifier used to declare an enum constant in this type. Extraneous whitespace characters are not permitted.

values()        

Returns an array containing the enum constants of the operation type (CALL or SMS) in the order that they were declared.

The method may be used to iterate over the constants as follows:

for (SrnRemoteBuiltInAction.OperationType c :

        SrnRemoteBuiltInAction.OperationType.values())

 System.out.println(c);

To specify a remote built-in call action:

SrnRemoteBuiltInAction remoteBuiltInAction = new SrnRemoteBuiltInAction("Call");
remoteBuiltInAction.setType(SrnRemoteBuiltInAction.OperationType.CALL);
remoteBuiltInAction.setData(Uri.fromParts("tel", "+821095557811", null));
myActions.add(remoteBuiltInAction);

To specify a remote built-in SMS action:

SrnRemoteBuiltInAction myAction = new SrnRemoteBuiltInAction("SMS");
 
myAction.setType(OperationType.SMS);
   // Optionally specifies the number to SMS.
myAction.setData(Uri.fromParts("sms", "+14157364480", null));
   // Optionally specifies an Android intent that will be invoked.
Intent resultIntent = new Intent(this, MyActivity.class);
 
...
 
myAction.setCallbackIntent(CallbackIntent.getActivityCallback(resultIntent));myActions.add(myAction);

Remote Input Actions

Remote input actions can be used to prompt the Gear end-user for input:

KEYBOARD

MULTI_SELECT 

SINGLE_SELECT

The user can enter text using 1 of 3 types of device keyboards.

The user can choose 0, 1, more selections from a specified list.  

The user can choose 0 or 1 selection from a specified list.

The Gear device manages getting the user input and returning it to the Android app. Execution of the action based on user input is managed by the Android app via an Android intent.

NOTE:   Single-select and multi-select input modes must specify at least one choice.

The user's entry can be retrieved from the Android intent’s extras with the key: SAMSUNG_REMOTE_INPUT_RESULT.

SrnRemoteInputAction.InputModeFactory

createKeyboardInputMode ()   

Instantiates a KeyboardInputMode object of the NORMAL (typically QWERTY) keyboard type to get user input.

Returns:

The new KeyboardInputMode.

createKeyboardInputMode (keyboardType)                 

Instantiates a KeyboardInputMode object of the specified preferred type of device keyboard to be initially displayed (when available on the device) to get user input.

keyboardType

     NORMAL

     NUMBER

     EMOJI

Preferred type of device keyboard:

      Default Standard device keyboard (typically alphanumeric/symbol QWERTY).

      Numeric-character-only keyboard.

      Graphic-symbol-only keyboard (similar to ASCII emoticons).

Returns:

The new KeyboardInputMode.

createMultiSelectInputMode ()

Instantiates a MultiSelectInputMode object to get 0, 1, or more user selections.

Returns:

The new MultiSelectInputMode.

createSingleSelectInputMode ()

Instantiates a MultiSelectInputMode object to get 0, 1, or more user selections.

Returns:

The new MultiSelectInputMode.

SrnRemoteInputAction

SrnRemoteInpuAction(label)     

Constructs a keyboard user-input action managed by the Gear device with the specified name.   Keyboard mode is the default input mode.

label

Name of the remote input action displayed in the UI.

SrnRemoteInput(label, inputMode)        

Constructs a user-input action managed by the Gear device with the specified name and type of input.

label

inputMode

  

Name of the remote input action displayed in the UI.

Type of Gear user input:

KeyboardInputMode — Default Keyboard entry, subject to SrnRemoteInputAction.KeyboardInputMode.

MultiSelectInputMode — User-tap entry of 1 or more specified UI selections.

SingleSelectInputMode — User-tap entry of only 1 of the specified UI selections.

setDescription()

Specifies the brief purpose or explanation of the action to be displayed in the UI.

description

Purpose or explanation of the action.

Whether and when the description is displayed depends on the input mode decided by the client, and by its UX/UI model.

It is recommended to always specify a description.

setIcon()

Specifies the icon image used in the remote input action UI buttons.

icon

Name of the action's UI button icon image asset.

Note: When setIcon() is specified, its setting will override a remote input constructor that specifies a UI button icon.

setRequestedInputMode()

Specifies the preferred user input mode to be requested upon user-initiation of the action.

inputMode

Input mode to be requested (for example, touchscreen, microphone, on-screen keyboard).

When the requested mode is supported by the client, the requested mode will be used. When not supported, the client will determine to set another mode or generate an error for the rich notification.

Keyboard Input Mode

An RN action can get a user entry from a standard QWERTY, numeric, or emoji keyboard when supported by the Gear device. Users can be aided by pre-entered content and limited by a maximum number of characters.

SrnRemoteInputAction.KeyboardInputMode

setCharacterLimit()

Specifies the maximum number of keyboard characters to be entered

characterLimit

Maximum number of characters

setKeyboardType()

Specifies the preferred type of device keyboard to be initially displayed (when available on the device) to get user input.

keyboardType

     NORMAL

     NUMBER

     EMOJI

Preferred type of device keyboard:

     Default Standard device keyboard (typically alphanumeric/symbol QWERTY)

     Numeric-character-only keyboard

     Graphic-symbol-only keyboard (similar to ASCII emoticons)

setPrefillString()

Specifies the text string for the initial, default entry

prefillString

Text string for default entry

 

This method may be used with wearable devices that do not support a UI display, but do support a speaker and a microphone.

To specify a remote input keyboard action:

SrnRemoteInputAction keyRemoteInputAction = new SrnRemoteInputAction("Send Us Your 
                                                                                Comments");
Intent keyboardIntent = new Intent(context, RichNotificationActivity.class);

KeyboardInputMode keyboardInputMode = InputModeFactory.createKeyboardInputMode();
keyboardInputMode.setPrefillString("@name");
keyboardInputMode.setCharacterLimit(140);
keyboardInputMode.setKeyboardType(KeyboardType.NORMAL);
keyRemoteInputAction.setRequestedInputMode(keyboardInputMode);
keyRemoteInputAction.setCallbackIntent(CallbackIntent
                                                   .getActivityCallback(keyboardIntent));
myActions.add(keyRemoteInputAction);

Multi-Select Input Mode

An RN action can get 0, 1, or more user selections from a specified list of available choices, each identified by a UI label and a code that is returned. When all choices specify an icon and the device supports icon display, each available choice also displays its associated icon.

SrnRemoteInputAction.MultiSelectInputMode

Note: Any number of one or more types of addChoice methods can be used in one rich notification.

addChoice(label, choiceID)

Adds one user option with the specified label and ID. A dot icon is used for the option's UI button

label

choiceID

Descriptive UI label text displayed near the option's UI button

Identifying value (positive integer within Android limits) of the option that is returned after user selection and choice completion

addChoice(label, choiceID, icon)

Adds one user option with the specified label, ID, and UI button icon

label

choiceID

icon

Descriptive UI label text displayed near the choice's UI button

Identifying value (positive integer within Android limits) of the option that is returned after user selection and choice completion

Name of the option's UI button icon image asset

Note: For ANY user choice to display an associated icon, ALL user choices must specify an icon, or else icons will not be displayed for ALL choice items

addChoice
(label, choiceID, icon, selected)

Adds one user option with the specified label, ID, and UI button icon

label

choiceID

icon
 

selected

true
 

false

Text of the UI label displayed near the choice's UI button that explains the choice

Identifying value (positive integer within Android limits) of the option that is returned after user selection and choice completion

Name of the option's UI button icon image asset
Note: For ANY user choice to display an icon, ALL user choices must specify an icon

Whether or not the option is pre-selected when displayed:

The added option is pre-selected
The user can unselect options that have been pre‑selected

The added option is NOT pre-selected

To specify a remote input multi-select action:

SrnRemoteInputAction multiRemoteInputAction = new SrnRemoteInputAction("Favorite Forecast 
                                                                                Qualities");
SrnRemoteInputAction.MultiSelectInputMode multiSelectInputMode = InputModeFactory.createMultiSelectInputMode();

multiRemoteInputAction.setDescription("Select the qualities of the forecast service that 
                                                                                you like.");
multiSelectInputMode.addChoice("Accuracy", "02");
multiSelectInputMode.addChoice("Preciseness", "04");
multiSelectInputMode.addChoice("Up-to-the-minute", "06");
multiSelectInputMode.addChoice("Localized", "08");

multiRemoteInputAction.setRequestedInputMode(multiSelectInputMode);

Intent multipleSelectIntent = new Intent(mContext, RichNotificationActivity.class);
multiRemoteInputAction.setCallbackIntent(CallbackIntent
                                     .getActivityCallback(multipleSelectIntent));

myActions.add(multiRemoteInputAction);

Single-Select Input Mode

An RN action can get 0 or 1 user selections from a specified list of available choices, each identified by a UI label and a code that is returned. When ALL choices specify an icon and the device supports icon display, each available choice also displays its associated icon.

SrnRemoteInputAction.SingleSelectInputMode

Note: Any number of one or both types of addChoice methods can be used in one rich notification.

addChoice(label, choiceID)        

Adds one user option with the specified label and ID.

label

choiceID

Descriptive UI label text displayed near the option's UI button.

Identifying value of the option that is returned after user selection and choice completion.

addChoice(label, choiceID, icon)

Adds one user option with the specified label, ID, and UI button icon

label

choiceID

icon

Descriptive UI label text displayed near the option's UI button

Identifying value (positive integer within Android limits)  of the option that is returned after user selection and choice completion.

Name of the image asset for the option's UI icon

Note: For any user choice to display an associated icon, all user choices must specify an icon, or else icons will not be displayed for all choice items.

To specify a remote input single-select action:

SingleSelectInputMode singleInputMode = InputModeFactory.createSingleSelectInputMode();
singleInputMode.addChoice("Yes", "01");
singleInputMode.addChoice("No", "02");
singleInputMode.addChoice("Maybe", "03");
singleInputMode.addChoice("Don't know", "04");

singleRemoteInputAction.setRequestedInputMode(singleInputMode);
singleRemoteInputAction.setDescription("Do you think the forecast will come true?");

Intent singleSelectIntent = new Intent(mContext, SrnRichNotification.class);
singleRemoteInputAction
 .setCallbackIntent(CallbackIntent.getActivityCallback(singleSelectIntent));

myActions.add(singleRemoteInputAction);

 

  • Was this article helpful?