Tracker Definition

Health Service helps to create a tracker provider application that contains your own tracker. Your defined tracker is located on the Samsung Health > Manage items menu after installing your application and will be shown on the Samsung Health's main screen upon the user‘s subscription.

You need to check the existing Samsung Health tracker before the new tracker definition. Define your application's tracker and design the tracker tile with the SDK's Health Service only if there is no proper tracker to express your application's health data on Samsung Health.

The left screenshot of Figure 9 shows an added tracker of your installed application to the tracker list. If the user turns on the “Sample” tracker on the page and is back to the Samsung Health's main screen, its tracker tile will be shown as the right screenshot of Figure 9.

Health Service provides three tracker tile templates to express the user's health data with an icon, a title, a button with intent, a data value and a unit, and tile intent. You can choose the proper tile type and make a natural service connection to your application with the tracker tile's intent and the button intent.

Figure 9: Sample tracker tile on Samsung Health Figure 9: Sample tracker tile on Samsung Health

Tracker Definition

A tracker for your application can be defined as covering somewhat of a wide scope like 'My Exercise' that includes running, walking and swimming. Or it can be 'Walking Steps' in a narrower scope.

The tracker is defined with the Json formatted metadata structure in the manifest. It has the following fields shown in Table 4. Please be careful not to define one more tracker.

Field Description
id Tracker ID.
  • Starts with the 'tracker.' prefix

  • Needs to be unique in your application

  • No space or additional dot

    • (O) \"tracker.myexcercise\"

    • (X) \"mytracker.walk\" - caused by the different prefix

    • (X) \"tracker.my walking steps\" - caused by spaces

    • (X) \"tracker.myexercise.walk\" - caused by an additional dot

display-name String resource ID of the displayed name for the tracker.
  • The value of the string resource ID in 'strings.xml' will be displayed in tracker items of Samsung Health.

  • If your application covers more than one locale, add translated display names for supported locales to string resources.

  • Do not make it too long as considering the width of the device display.

icon Drawable resource name for the icon.
  • Size: 36 * 36 dp

controller Class name that implements TrackerEventListener
Table 4: Tracker metadata

The following example shows the tracker definition.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="testtracker_manifest">
{
    \"tracker\" : {
        \"id\" : \"tracker.test\",
        \"display-name\" : \"tracker_display_name\",
        \"icon\" : \"tracker_icon\",
        \"controller\" : \"com.samsung.android.app.plugintracker.MyTracker\"
    }
}
    </string>
</resources>

The defined tracker is shown in tracker items of Samsung Health as Figure 10 after installing your tracker provider application. All information in the manifest above is used for your tracker in Samsung Health > Manage items. The "tracker_icon" icon resource is shown inside the blue box region in Figure 10. The "tracker_display_name" resource is shown as the tracker's title after the icon in the same page.

Figure 10: Icon in Samsung Health > Manage items Figure 10: Icon in Samsung Health > Manage items

Tracker Tile Templates

Your tracker's tile can be expressed with the defined time templates and it contains following properties:

  • Brand icon

  • Health data and its unit

  • Measured time of data

  • Title

  • Button with its text and intent

Intent to jump to detailed health information or start a specific action such as measurements can be added on the tracker tile also. Tracker tiles for your tracker are displayed on the main screen of Samsung Health after the user subscribes to the tracker.

A tracker tile visualizes a tracker's health data within a rectangular box on the main screen of Samsung Health. It displays the latest data collected by its tracker such as calories burned, running distance, or number of activities. A tracker can be expressed as a tracker tile on the Samsung Health's main screen with various type templates depending on interested information related to health data.

  • TRACKER_TILE_TYPE_1

  • TRACKER_TILE_TYPE_2

  • TRACKER_TILE_TYPE_3

If you need detailed design guidelines, see "Tracker Design Guidelines". You can also find it under the [SamsungHealthSDK]/Service/Docs/ folder.

TRACKER_TILE_TYPE_1

TRACKER_TILE_TYPE_1 is useful when you need to show the tracker tile without content value. It contains the icon, title, and button as Figure 11.

Figure 11: Tracker tile without content value (type 1) Figure 11: Tracker tile without content value (type 1)
TRACKER_TILE_TYPE_2

If there is data value to show and no need of a button, use TRACKER_TILE_TYPE_2. It contains the icon, content value, unit, title, and date.

Figure 12: Tracker tile without button (type 2) Figure 12: Tracker tile without button (type 2)
TRACKER_TILE_TYPE_3

TRACKER_TILE_TYPE_3 contains a button for the specific action additionally as comparing with TRACKER_TILE_TYPE_2.

Figure 13: Tracker tile with button (type 3) Figure 13: Tracker tile with button (type 3)

Table 5 shows all properties of the tracker tile.

Property Description
Icon Resource of the representative icon.
Content value* Numeric value of measured data to be shown.
Content unit* Unit of the content value.
It's optional.
Title* Title of the tracker tile.
Date Time point information for the tracker tile.
Button The followings can be set for the button.
  • Button text

  • Button intent

The designated color is applied to the button background.*
Table 5: Tracker tile properties

To define the tracker tile containing interesting information, select the proper tile type template and create a tile instance with the following TrackerTile‘s constructor.

  • TrackerTile(Context context, String trackerId, String tileId, int tileType)

The tracker tile can have intent with setContentIntent(int intentType, Intent intent) that performs an action such as jump to your application when the user selects the tile on the main screen of Samsung health.

The tile's background color is fixed in the platform but some properties of the tracker tile can be the brand color separately. Properties marked with * in Table 5 indicates ones that can be changed to its brand color. The brand color can be a single color with setContentColor(int contentColor).

Tracker Tile Manager

The created tracker tile instance is managed with TrackerTileManager. It enables you to:

  • Checks the posted your tracker tile on Samsung Health

  • Post or update your tracker tile

  • Remove your posted tracker tile

The tracker tile manager enables your application to post defined tracker tiles on the main screen or remove them from the main screen.

Figure 14 shows an internal flow how your tracker is posted to Samsung Health's main screen as a tracker tile.

  1. 1) Installed application provides a tracker as a plugin on Samsung Health.
  2. 2) The application's tracker is added to tracker items of Samsung Health.
  3. 3) The user checks trackers on the tracker item page of Samsung Health by selecting the '+' button on the main screen.
  4. 4) The user subscribes to your tracker.
  5. 5) The subscribed tracker's tile is posted to the Samsung Health's main screen.
Figure 14: Tracker tile of your application on Samsung Health Figure 14: Tracker tile of your application on Samsung Health

Tracker Tile Event Handling

The tracker tile event can be received from the main screen of Samsung Health in following cases

  • onSubscribed() is called if:

    • The suggestion tile is tapped on the Samsung Health's main screen.
    • The user subscribes your tracker on Samsung Health.
  • onUnsubscribed() is called if:

    • The user unsubscribes your tracker on Samsung Health.
  • onPaused() is called if:

    • The main screen of Samsung Health goes to the background.
  • onTileRequested() is called if:

    • The main screen of Samsung Health is resumed.
  • onTileRemoved() is called if:

    • The user removes the posted tracker tile from the main screen of Samsung Health.

And you can add intent to your tracker tile itself or its button to link to the specific activity or service.