Programming GuideApr 27, 2017

Overview

Samsung Health is an application that monitors the user's activities and helps the user has a healthier life. Samsung Health's collected data can be categorized and expressed in various ways. It is important to present proper information to the user in the required time for advanced experiences. Samsung Health supports Android devices with KitKat 4.4 including non-Samsung devices.

Samsung Health SDK enables your app to work with Samsung Health. It provides the following packages.

  • Health Data

  • Health Service

The SDK can be downloaded from the developer site. See development environment for more information.

This document contains descriptions for the SDK's Health Service. See the Health Data's documents if you want to synchronize health data with Samsung Health.

The Health Service of Samsung Health SDK provides the tracker feature to:

Table 1 includes the SDK's Health Service glossary.

Term Description
Samsung Health An application that helps monitor the user's activities and helps the user makes a healthier life.
It contains the ‘main screen' area that shows tracker tiles.
It's written as italic in this document.
tracker The tracker is the basic building block of Samsung Health.
See 6.1 for more information.
tracker tile The tracker tile is a unit of viewer for the specific tracker on Samsung Health. It represents the latest data collected by its tracker and can be a gateway.
See 7.2 for more information.
tracker items It's the item list that shows all trackers in Samsung Health.
Table 1: Glossary
Architecture

The SDK's Health Service is composed of the following features roughly.

  • Tracker manager

  • Tracker tile manager

The tracker manager provides information the Samsung Health's tracker and helps to launch the Samsung Health's available tracker.

The tracker tile manager provides the plugin service to install your app's tracker on Samsung Health. Your tracker is shown in the tracker item list page of Samsung Health with existing trackers if the application is registered as the partner application of Samsung Health. If the user subscribes to your app's tracker, its tile is posted to the Samsung Health's main screen.

Figure 1 shows the architecture of the SDK’s Health Service and Samsung Health's related features.

Figure 1: Architecture for SDK's Health Service and Samsung Health Figure 1: Architecture for SDK's Health Service and Samsung Health
Class Relationship

The SDK's Health Service library provides the following packages:

  • com.samsung.android.sdk.shealth

  • com.samsung.android.sdk.shealth.tracker

All APIs of the com.samsung.android.sdk.shealth.tracker package can be used after the following API succeeds.

  • Shealth.initialize(Context) of the com.samsung.android.sdk.shealth

com.samsung.android.sdk.shealth.tracker enables your app to use Samsung Health's tracker feature.

Figure 2 shows Health Service's class relationship.

Figure 2: Health Service's class relationship Figure 2: Health Service's class relationship

Each partner app can define only one tracker. Health Service's Plugin Service adds the app's defined tracker into the Samsung Health's tracker items. TrackerEventListener receives Samsung Health's tracker events. TrackerManager posts the app's tracker with TrackerTile with templates.

TrackerManager gets Samsung Health's tracker information and helps your app to launch the tracker if it is available. Note that launching a Samsung Health's tracker works on Samsung Health 4.8 or above.

Interfaces and classes of Health Service are described in Table 2. See API Reference for more information. You can find it under the [SamsungHealthSDK]/Service/Docs/API_Reference folder.

com.samsung.android.sdk.shealth
Interface / Class Description
Shealth This class is a representative class of the Health Service library. It helps on the usage of APIs in the com.samsung.android.sdk.shealth.tracker package.
com.samsung.android.sdk.shealth.tracker
Interface / Class Description
TrackerEventListener This interface defines event handlers related to your app's tracker in Samsung Health.
TrackerInfo This class provides tracker information.
It works on Samsung Health 4.8 or above.
TrackerManager This class provides S Health's tracker information and help to launch the Samsung Health's available tracker.
It works on Samsung Health 4.8 or above.
TrackerTile This class defines the app tracker's tile.
TrackerTileManager This class is used to post or remove a tracker tile on the Samsung Health.
Table 2: Interfaces and classes of the Health Service library

Development Environment

Check prerequisites first and follow all steps below to create a Samsung Health's partner app.

Prerequisites

Check following prerequisites before downloading Samsung Health SDK.

Android Version

Android 4.4 KitKat (API Level 19) or above

Available Devices

Android smartphones including non-Samsung devices

Samsung Health Version

Samsung Health's partner app runs with Samsung Health 4.0 or above.

Downloading Samsung Health SDK

Samsung Health SDK can be downloaded on the Samsung developer site. You can find the following content in the SDK's Health Service.

Folder in SDK Description
Docs
  • API Reference
    Describes the SDK's Health Service APIs
  • Programming Guide
    Contains development information to create a Samsung Health's partner app with Health Service
  • Tracker Design Guidelines
    Guidelines for designing the app's tracker and tracker tile to add to Samsung Health
Libs
  • samsung-health-service-va.b.c.jar
    Health Service library of Samsung Health SDK
  • sdk-v1.0.0.jar
    Samsung SDK basic library
Samples
  • PluginTracker
    Sample app created by using the Health Service library. This app posts its sample tracker tile to Samsung Health and launches a specific Samsung Health's tracker.
Table 3: Samsung Health SDK's Health Service content

Development Process

If you checked prerequisites and downloaded the SDK, it's ready to create your application. Make it with the following steps.

Checking Samsung Health's Trackers

Health Service is related deeply to the Samsung Health's tracker feature. Samsung Health provides useful trackers. Find Samsung Health > Manage items:

  • Use Samsung Health's each tracker.

  • Check the tracker operation on Samsung Health.

  • Find a similar existing Samsung Health's tracker before defining a new tracker for your app.

Note

Existing Samsung Health's trackers need to be considered first before creating an app's tracker. If the app's tracker is duplicated with Samsung Health's exiting tracker, the app may be rejected as the partner app.

Creating an Application

Create your app with the SDK. Hello Tracker Provider shows how to use Health Service.

Data Synchronization with Samsung Health

Health data synchronization with Samsung Health is essential to use the SDK. The SDK supports useful data types.

If your desired data type for your app, you can read Samsung Health‘s data or write your app's data to Samsung Health through the SDK's Health Data. An app that defines its own tracker without data synchronization can be rejected as Samsung Health's partner apps. See more Health Data documents.

Testing Your Application

The app that uses the SDK works with Samsung Health after the partner app approval. It needs to be tested fully before applying for the partner app. The SDK provides the following environments.

  • Samsung Health‘s developer mode

  • Checklist for Samsung Health's partner app

You can apply for Samsung Health's partner app before publishing your app. Otherwise the app publication can be first before applying for partner app. The former is proper to provide a seamless service of your app.

Note

Samsung Health SDK doesn't support the Emulator test. Android 4.4 KitKat (API level 19) device or above is required to test your app.

Samsung Health's Developer Mode

Samsung Health provides the developer mode for the test before the partner app approval. The Samsung Health's developer mode is not activated by default. You can activate it with the following steps.

  1. 1) Select the action overflow of Samsung Health on the top-right side.
  2. 2) Find Settings > About Samsung Health in the action list.
  3. 3) Tap the version region quickly for 10 times.
    The exact region, illustrated in the red and blue box of Figure 3 needs to be tapped.
  4. 4) If it succeeds, "*(Developer Mode)*" is shown in front of the version and it means the developer mode is activated. Now you can test your app with Samsung Health.

Figure 3 shows how to turn on or off the developer mode in Samsung Health. If you tap the version region quickly for 10 times in the developer mode as the right figure, the developer mode is deactivated.

Figure 3: On or off of Samsung Health's developer mode Figure 3: On or off of Samsung Health's developer mode
Checklist for Samsung Health's Partner App

Samsung Health SDK provides a checklist that includes basic test items for the app test. Download it here and check your app before applying for partner app. It helps you save the time on the registration process for Samsung Health's partner app.

Publishing Your Application

If your application is ready, make a package and publish it on the app market such as Google Play.

Requesting for Partner Apps

The application will work properly with Samsung Health after the partner app approval. Samsung Health team checks the app's violations and registers your app as the Samsung Health's partner because health data is closely connected to the privacy issue.

You can request for the partner application on the developer site.

Note

Only the approved partner app runs with Samsung Health. Otherwise the application can be run tested on the developer mode.

Hello Tracker Provider

This chapter describes how to create a simple tracker provider with the SDK. Create a new Android application project and follow the basic steps below.

  • Importing Libraries

  • Connection to Samsung Health

  • Initialization

  • Feature Availability

  • Posting Your App's Tracker

Detailed descriptions are below.

Importing Libraries

Not only the SDK's Health Service, but also Health Data are required to use the tracker feature. Add the following libraries to the "libs" folder in your created application project.

  • samsung-health-data-a.b.c.jar

  • samsung-health-service-va.b.c.jar

  • sdk-v1.0.0.jar

Connection to Samsung Health

Samsung Health SDK works with Samsung Health 4.0 or above. Samsung Health installation and the installed Samsung Health‘s version need to be checked before calling the Health Service's APIs.

See the related FAQ or Health Data's Programing Guide's 4.2 for more information.

Initialization

Initializing the Health Service with the following API is needed to use its other APIs.

  • initialize(Context)of the com.samsung.android.sdk.shealth.Shealth class.

import com.samsung.android.sdk.shealth.Shealth;

import android.app.Application;
import android.content.Context;
import android.util.Log;

public class PluginTracker extends Application {

    private static final String APP_TAG = "PluginTracker";

    @Override
    public void onCreate() {
        super.onCreate();
        Shealth shealth = new Shealth();
        try {
            shealth.initialize(mContext);
        } catch (Exception e1) {
            Log.d(APP_TAG, "Samsung Health Service Initialization failed." + e.toString());
        }
    }
}
Feature Availability

A certain Health Service's feature works on the specific Samsung Health's version or above because the tracker feature is deeply integrated to Samsung Health. E.g., FEATURE_TRACKER_LAUNCH works on Samsung Health 4.8 or above.

Check the feature availability of your desired feature in Health Service. If any feature is not available, upgrade Samsung Health to the latest version.

// Check the feature availability for all wanted features.
    if (mShealth.isFeatureEnabled(Shealth.FEATURE_TRACKER, Shealth.FEATURE_TRACKER_LAUNCH)) {

        // All wanted features are available.
        // You can use all APIs of the "com.samsung.android.sdk.shealth" package.

    } else {
        // If any feature is not available, Samsung Health should be upgraded.
        Log.d(APP_TAG, "Samsung Health should be upgraded");

        // Let the user upgrade Samsung Health to the latest version.
        Intent intent;
        intent = new Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=com.sec.android.app.shealth"));
        this.startActivity(intent);
    }
Posting Your App's Tracker

If you cannot find a wanted tracker on Samsung Health, you can define your app's own tracker.

Manifest for Tracker Definition

A new tracker can be defined in the manifest file as shown below. An ID, displayed name, icon and controller are required for the tracker definition. For more information, refer to 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>
Registration of Plugin Service

The tracker of your application is installed as plugin for Samsung Health by registering it for the plugin service with your defined tracker ID and its resource name in AndroidManifest.xml of your application project.

<service
    android:name="com.samsung.android.sdk.shealth.PluginService"
    android:exported="true" >
    <meta-data
        android:name="tracker.test" android:value="@string/testtracker_manifest"/>
</service>
  • android:name - the tracker ID of the tracker manifest file.

  • android:value - the resource name of the tracker manifest file.

Handling Event from Samsung Health

Samsung Health sends its events to your application through TrackerEventListener and your app can handle them by implementing TrackerEventListener.

TrackerEventListener can be implemented basically as shown below.

public class MyTracker implements TrackerEventListener {

    private TrackerTileManager mTrackerTileManager;

    public MyTracker() {
        // A default constructor has to be created.
    }

    @Override
    public void onCreate(Context context, String trackerId) {
        Log.d(APP_TAG, "onCreate(" + trackerId + ")");

        if (mTrackerTileManager == null) {
            try {
                mTrackerTileManager = new TrackerTileManager(context);
            } catch (IllegalArgumentException e) {
                Log.d(APP_TAG, "MyTracker onCreate() - IllegalArgumentException");
            }
        }
    }

    @Override
    public void onSubscribed(Context context, String trackerId) {
        Log.d(APP_TAG, "onSubscribed(" + trackerId + ")");
        // User changed the subscription state of your tracker to subscribe.

        // Post your tracker tile here to show it on the Samsung Health's main screen
        // right after user subscribed your tracker.

        // If you miss posting your tracker tile here and post it in onTileRequested(),
        // your tracker tile will not be shown on the main screen
        // until onTileRequested() is called.

        // TRACKER_TILE_TYPE_1 is used generally if there is no data yet.
    }

    @Override
    public void onUnsubscribed(Context context, String trackerId) {
        Log.d(APP_TAG, "onUnsubscribed(" + trackerId + ")");
        // User changed the subscription state of your tracker to unsubscribe.
    }

    @Override
    public void onPaused(Context context, String trackerId) {
        Log.d(APP_TAG, "onPaused(" + trackerId + ")");
        // Samsung Health went to the background.
        // Stop posting tracker tiles.
    }

    @Override
    public void onTileRequested(Context context, String trackerId, String tileId) {
        Log.d(APP_TAG, "onTileRequested(" + trackerId + ", " + tileId + ")");
        // Samsung Health has been resumed on the foreground.

        // If tileId is null, it means there is no posted tracker tile successfully on the main screen.
        // Set the tracker ID if it's null.

        // Post your tracker tile here.
        // TRACKER_TILE_TYPE_1 is used generally if there is no data yet.

        // Or you can update the posted tracker tile with updated data here.
    }

    @Override
    public void onTileRemoved(Context context, String trackerId, String tileId) {
        Log.d(APP_TAG, "onTileRemoved(" + trackerId + ", " + tileId + ")");
        // User removed your posted tracker tile from the main screen.
    }
}

When you implement TrackerEventListener, the implemented class's default constructor is mandatory. E.g. if implemented class name is 'MyTracker', create its default constructor as shown below. Or your application won't receive Samsung Health‘s events well.

public class MyTracker implements TrackerEventListener {

    public MyTracker() {
        // An empty constructor should be created.
    }
}
Creating a TrackerTileManager's Instance

TrackerTileManager enables your application to post or remove your tracker's tile.

public class MyTracker implements TrackerEventListener {

    private TrackerTileManager mTrackerTileManager;

    public MyTracker(Context context) {
        if (mTrackerTileManager == null) {
            try {
                mTrackerTileManager = new TrackerTileManager(context);
            } catch (IllegalArgumentException e) {
                Log.d(APP_TAG, "MyTracker Constructor - " + e.toString());
            }
        }
    }
}
Creating Tracker Tile's Intent

If you want to add service intent for a tile's button to be performed in background, the service intent can be defined as the following example.

final public class MyTrackerService extends IntentService {

    private static final String APP_TAG = "PluginTracker";

    private static final String SHARED_PREFERENCE_NAME = "tile_content";
    private static final String SHARED_PREFERENCE_CONTENT_VALUE_KEY = "content_value";
    private static final String VALIDATION_KEY = "validation_key";

    @Override
    protected void onHandleIntent(Intent intent) {

        if (intent == null) {
            return;
        }

        String trackerId = intent.getStringExtra(TrackerTileManager.EXTRA_TRACKER_ID);
        if (trackerId == null) {
            return;
        }

        String tileId = intent.getStringExtra(TrackerTileManager.EXTRA_TILE_ID);
        if (tileId == null) {
            return;
        }

        String validationValue = intent.getStringExtra(VALIDATION_KEY);
        SharedPreferences sp = getSharedPreferences(SHARED_PREFERENCE_NAME, Context.MODE_PRIVATE);
        String validationSavedValue = sp.getString(VALIDATION_KEY, "");

        if (validationValue.isEmpty() || !validationValue.equals(validationSavedValue)) {
            Log.d(APP_TAG, "invalid validation value");
            return;
        }

        int tileContent = sp.getInt(SHARED_PREFERENCE_CONTENT_VALUE_KEY, 0) + 1;
        Log.d(APP_TAG, "content value : " + String.valueOf(tileContent));
        sp.edit().putInt(SHARED_PREFERENCE_CONTENT_VALUE_KEY, tileContent).apply();

        MyTracker tracker = new MyTracker(this);
        tracker.updateTile(this, trackerId, tileId);
    }
}
Posting a Tracker Tile

If the user subscribes to your tracker on the Samsung Health's tracker item list, Samsung Health sends an event to onSubscribed() of your application. Post your tracker tile in this event handler to show your tracker tile on the Samsung Health's main screen right after the user subscribes to your tracker. Keep in mind that a tracker tile will not be posted if the Samsung Health‘s main screen is in pause state.

public class MyTracker implements TrackerEventListener {

    private static final String MY_TILE_ID = "hello_tile";

    @Override
    public void onSubscribed(Context context, String trackerId) {
        // Your tracker is subscribed.
        Log.d(APP_TAG, "onSubscribed(" + trackerId + ")");

        postDefaultTile(context, trackerId, MY_TILE_ID);
    }
}

In case that there is no data for your tracker, use TRACKER_TILE_TYPE_1 with an icon, title and button. See 7.2 for more information. The following code shows how to post a TRACKER_TILE_TYPE_1 tracker tile.

public class MyTracker implements TrackerEventListener {

    private int mTemplate = TrackerTile.TRACKER_TILE_TYPE_1;

private void postDefaultTile(Context context, String trackerId, String tileId) {
        TrackerTile myTrackerTile;
        Intent launchIntent;

        // Your tracker tile is not posted successfully on the main screen of Samsung Health.
        // Set the tile ID. Or the tile will not be shown though you call TrackerTileManager.post().
        if (tileId == null) {
            tileId = MY_TILE_ID;
        }

        try {
            // Create Intent to do an action
            // when the tracker tile is clicked
            launchIntent = new Intent(context, MainActivity.class);

            // Create Intent to do an action
            // when the button on this tile is clicked
            Intent serviceIntent = new Intent(context, MyTrackerService.class);

            // Create TrackerTile with type 1 and set each values and intents
            myTrackerTile = new TrackerTile(context, trackerId, tileId, mTemplate);

            // Set Title
            myTrackerTile
                    .setTitle(R.string.tracker_test_display_name)
                    // Set Icon resource
                    .setIcon(R.drawable.tracker_icon)
                    // Set content color
                    .setContentColor(context.getResources().getColor(R.color.tracker_content_color))
                    // Set content intent
                    .setContentIntent(TrackerTile.INTENT_TYPE_ACTIVITY, launchIntent)
                    // Set button intent
                    .setButtonIntent("START", TrackerTile.INTENT_TYPE_SERVICE, serviceIntent);

            if (mTrackerTileManager != null) {
                mTrackerTileManager.post(myTrackerTile);
            }

        } catch (IllegalArgumentException e) {
            Log.d(APP_TAG, "MyTracker postDefaultTile(" + trackerId + ", " + tileId + ") " + e.toString());
        } catch (NotFoundException e) {
            Log.d(APP_TAG, "MyTracker postDefaultTile(" + trackerId + ", " + tileId + ") " + e.toString());
        }
    }
}

Make sure that Samsung Health is on the developer mode before installing your application. Samsung Health will suggest your new tracker on its main screen and you can add tracker easily by tapping the suggestion tile as Figure 4.

Figure 4: Posted tracker tile on Samsung Health Figure 4: Posted tracker tile on Samsung Health
Updating the Posted Tracker Tile

When the main screen is resumed on the foreground, implemented
TrackerEventListener.onTileRequested() of your application receives an event from Samsung Health. You can post a tracker tile or update the posted tile here.

public class MyTracker implements TrackerEventListener {

    @Override
    public void onTileRequested(Context context, String trackerId, String tileId) {
        // The main screen requested the tracker tile.
        Log.d(APP_TAG, "onTileRequested(" + trackerId + ", " + tileId + ")");

        // Update your tracker tile.
        updateTile(context, trackerId, tileId);
    }
}

If the application has health related data to show it on the tracker tile, use the TRACKER_TILE_TYPE_2 or TRACKER_TILE_TYPE_3 tracker tile type.

If there is no posted tracker tile on the main screen, the tile ID is received as null in the event handler above. To post a tracker tile on the main screen, the tile ID must be specified.

The following code shows how to update the posted tracker tile with TRACKER_TILE_TYPE_3.

public class MyTracker implements TrackerEventListener {

    public void updateTile(Context context, String trackerId, String tileId) {

        TrackerTile myTrackerTile = null;
        Intent launchIntent;

        // Set the measured value of the data
        int tileContentValue;
        // Set the measured time of the data
        int tileDate;

        // Your tracker tile is not posted successfully on the main screen of Samsung Health.
        // Set the tile ID. Or the tile will not be shown though you call TrackerTileManager.post().
        if (tileId == null) {
            tileId = MY_TILE_ID;
        }

        try {
            // Create Intent to do an action
            // when the tracker tile is clicked
            launchIntent = new Intent(context, MainActivity.class);

            // Create Intent to do an action
            // when the button on this tile is clicked
            Intent serviceIntent = new Intent(context, MyTrackerService.class);

            // Set template
            mTemplate = TrackerTile.TRACKER_TILE_TYPE_3;

            // Create TrackerTile and set each values and intents
            myTrackerTile = new TrackerTile(context, trackerId, tileId, mTemplate);

            // Set Title
            myTrackerTile
                    .setTitle(R.string.tracker_display_name)
                    // Set Icon resource
                    .setIcon(R.drawable.tracker_icon_30x30)
                    // Set content value
                    .setContentValue(String.valueOf(tileContentValue))
                    // Set content unit
                    .setContentUnit("LBS")
                    // Set Date text
                    .setDate(tileDate)
                    // Set content color
                    .setContentColor(Color.parseColor("#7CB342"))
                    // Set content intent
                    .setContentIntent(TrackerTile.INTENT_TYPE_ACTIVITY, launchIntent)
                    // Set button intent
                    .setButtonIntent("UPDATE", TrackerTile.INTENT_TYPE_SERVICE, serviceIntent);

            if (mTrackerTileManager != null) {
                mTrackerTileManager.post(myTrackerTile);
            }

        } catch (IllegalArgumentException e) {
            Log.d(APP_TAG, "MyTracker updateTile(" + trackerId + ", " + tileId + " " + e.toString());
        } catch (NotFoundException e) {
            Log.d(APP_TAG, "MyTracker updateTile(" + trackerId + ", " + tileId + " " + e.toString());
        }
    }
}

If you use the same tile ID with the posted tracker tile and update the tile, the updated tracker tile will be shown in the same position of the main screen as Figure 5 where the tracker tile has been posted. Otherwise, the updated tracker tile will be shown as the last tile on the main screen.

Figure 5: Updated tracker tile on Samsung Health Figure 5: Updated tracker tile on Samsung Health
Launching Samsung Health's Tracker

You can launch the Samsung Health's available tracker with the SDK's Health Service.

Creating a TrackerManager's Instance

Create a TrackerManager's instance first. Launching the Samsung Health's tracker is supported in Samsung Health 4.8 or above.

public class MainActivity extends Activity {

    private static final String APP_TAG = "PluginTracker";

    private TrackerManager mTrackerManager;

    private TrackerInfo getSpecificTrackerInfo(String trackerId) {

        // Construct a TrackerManager's instance
        try {
            mTrackerManager = new TrackerManager(this);
        } catch (IllegalArgumentException e) {
            Log.d(APP_TAG, "TrackerManager Constructor - " + e.toString());
        }

        // ...

    }
Getting Samsung Health's Tracker Info

The interesting tracker's information can be retrieved by TrackerManager. Check the tracker's availability also.

private TrackerInfo getSpecificTrackerInfo(String trackerId) {

		// ...

		// Get the tracker's info
		TrackerInfo trackerInfo = mTrackerManager.getTrackerInfo(TrackerManager.TRACKER_RUNNING);
		if(trackerInfo == null) {
				Log.d(APP_TAG, "trackerInfo == null");
				return null;
		}
		if(trackerInfo.isAvailable() == false) {
				Log.d(APP_TAG, "trackerInfo is not available.");
				return null;
		}

		return trackerInfo;
}
Launching the Available Tracker

If the tracker is available, you can launch it.

private void launchRunningTracker() {
		if(mTrackerManager == null) {
				Log.d(APP_TAG, "mTrackerManager == null");
				return;
		}

		// Get the wanted tracker's info
		TrackerInfo trackerInfo = getSpecificTrackerInfo(TrackerManager.TRACKER_RUNNING);
		if (trackerInfo == null) {
				Log.d(APP_TAG, "trackerInfo == null");
				return;
		}

		// Launch the tracker
		try {
				mTrackerManager.startActivity(this, trackerInfo.getId());
		} catch (IllegalArgumentException e) {
				Log.d(APP_TAG, "startActivity() - " + e.toString());
		} catch (IllegalStateException e) {
				Log.d(APP_TAG, "startActivity() - " + e.toString());
		}
}

The tracker and tracker tile are the basic features of Samsung Health. Your app can show the measured data on the Samsung Health's tracker or launch it through the SDK. Understanding the tracker and tracker tile's operation on Samsung Health is required first.

Tracker

The tracker is the basic building block of Samsung Health. The user's health data can be monitored, measured or updated through trackers such as counting steps, measuring heart rates, tracking exercises, collecting health data on background, or allowing the user to enter health data manually.

Samsung Health has various trackers for its supported data types already as Figure 6. Check the supported trackers on the tracker tab of Samsung Health > Manage items. The user can subscribe to the tracker by switching it on the tracker tab.

Figure 6: Samsung Health's trackers Figure 6: Samsung Health's trackers
Tracker Tile

The tracker is expressed to the user as the tracker tile. It is shown on the Samsung Health's main screen and represents the latest data collected by its tracker. It acts as a gateway when the user taps it. It's jumped to:

  • the tracker's detailed page in case that the Samsung Health tracker's tile

  • the app's specific page if it's the app tracker's tile.

The SDK enables an application to synchronize its health data with Samsung Health through the SDK's Health Data. If the application writes health data and the Samsung Health‘s related tracker exists, the tracker's tile is posted to the Samsung Health's main screen without the user's subscription.

For example, there is an application measures the blood pressure and writes the measured data to Samsung Health with the Health Data API. If it succeeds to write data to Samsung Health, Samsung Health posts its blood pressure tracker's tile with the measured value and time on Samsung Health automatically even the tracker has not been subscribed like Figure 7.

Figure 7: Operation of Samsung Health's tracker Figure 7: Operation of Samsung Health's tracker

It means that the app's doesn't need to define its tracker for the blood pressure on Samsung Health separately. Otherwise, the both tracker tiles of the app and Samsung Health will be posted at the same time with duplicated information. It would be not a good user experience definitely.

Tracker Manager

If Samsung Health has a proper tracker for your app's feature, the TrackerManager helps your app to launch the Samsung Health's available tracker.

Figure 8 shows the flow how to launch the Samsung Health's tracker.

  1. 1) The app gets the interesting tracker's info and checks its availability.
  2. 2) If it is, the app launches the tracker. The Samsung Health's tracker is foregrounded.
  3. 3) The user selects the back key and your app is foregrounded.
Figure 8: Launching the Samsung Health's tracker Figure 8: Launching the Samsung Health's tracker

See Launching Samsung Health's Tracker for an example.

Limitations

There are limitations on launching the Samsung Health's tracker.

  • It works on Samsung Health 4.8 or above.

  • Some trackers of Samsung Health may not be available by the local law or device specifications.
    Therefore, check the wanted tracker's availability before launching it.

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.

Health Service provides a sample application 'PluginTracker' to show how to post your tracker tile and work with Samsung Health. Check the sample application by importing its project with Android Studio (or Eclipse).

Prerequisites

Prerequisites to run PluginTracker are shown below.

  • Prepare an Android device that supports Android 4.4 KitKat (API level 19) or above.
    (Samsung and non-Samsung devices are available both.)

  • Install Samsung Health on the device.

  • Turn on the developer mode as 4.3.1.

  • Import PluginTracker with Android Studio (or Eclipse)

  • Run PluginTracker on the device.

Overview

If Samsung Health and PluginTracker are installed properly, you can:

  • find the Sample tracker on the Samsung Health‘s tracker list after installing the sample app.

  • Launch some Samsung Health's available tracker.

Figure 15: PluginTracker Figure 15: PluginTracker

If you subscribe to the Sample tracker and go back to the Samsung Health‘s main screen, its tile will be shown as the middle figure. Its tile is posted with TRACKER_TILE_TYPE_1 at the first time. The sample app's posted tile will be changed to the different tile template - TRACKER_TILE_TYPE_3 that includes a content value, unit, and updated time whenever the tile's button is tapped.

The posted tracker tile's ID can be checked on PluginTracker as the Figure 15's third screenshot and you can remove the posted tracker tile.

Connection to Health Data Store

The app needs to use the SDK's Health Data basically and connect to the health data store to handle various exceptions whether the app can work with Samsung Health on the device.

But PluginTracker doesn't include the Health Data API usage because it focuses to show the tracker usage only.

See the SimpleHealth sample application in the SDK or the Health Data‘s Programming Guide for the health data store connection.

Source Description

Table 6 describes source and resource files of PluginTracker.

Source / Resource Description
AndroidManifest.xml
  • Registering the tracker tile button's service intent (MyTrackerService) with the <service> element.

  • Declaring Samsung Health's PluginService with the <service> element.

res/values/
testtracker.xml Defining tracker with its metadata.
src/com/samsung/android/app/plugintracker/
MainActivity.java PluginTracker's main activity.
  • TrackerManager

    • Showing a list for some Samsung Health trackers.

    • Launching the selected tracker.

  • TrackerTileManager

    • Showing the posted tile's ID on the Samsung Health's main screen.

    • Containing a button to remove a posted tile.

MyTracker.java Checking the feature availability.
Implementing the app's tracker.
  • Implementing TrackerEventListener to receive the following tracker events from Samsung Health:

    • If the user subscribes or unsubscribes the PluginTracker's tracker,
      => onSubscribed(), onUnsubscribed()

    • If Samsung Health goes to the background,
      => onPaused()

    • If Samsung Health requests the tracker tile of PluginTracker,
      => onTileRequested()

    • If the posted tile is removed from the Samsung Health's main screen,
      => onTileRemoved()

  • Posting or updating the tracker tile of PluginTracker depending on the received tracker event.

PluginTrackerProvider.java Initializing the Health Service.
service/
MyTrackerService Defining the tracker tile's button intent to be performed in the background.
Table 6: PluginTracker's source description

See detailed implementation in the imported PluginsTracker's project through Android Studio (or Eclipse).