Scenario-Based Subscription Gives Users Key Insight on Health and Fitness

Many health and fitness apps provide a data subscription feature, which allows users to receive notifications in real time within the app, once their fitness or health records are updated, such as the day's step count, heart rate, or running distance.

However, tracking health and fitness over the long haul is not so easy. Real time notifications are less useful here. This can be a common challenge for fitness and health tracking apps, as meeting specific goals is not conducive for thinking over a long term. I have encountered this issue in my own fitness app. Let us say that a user of my app is trying to make an exercise plan. They set a long-term goal of walking for 10,000 steps for three times a week. When the step goal is achieved for the current day, my app will send a message with the day's step count. However, my app is still unable to notify the user whether the goal has been achieved for the week. That means, the user will have to check manually to see whether they have completed their long-term goals, which can be quite a hassle.

I stumbled across the scenario-based event subscription capability provided by HMS Core Health Kit, and tried integrating it into my app. Instead of subscribing to a single data type, I can now subscribe to specific scenarios, which entail the combination of one or more data types. In the example mentioned above, the scenario will be walking for 10,000 steps for any of the three days of a week. At the end of a week, my app will push a notification to the user, telling them whether they have met their goal.

After integrating the kit's scenario-based event subscription capability, my users have found it more convenient to track their long-term health and fitness goals. As a result, the user experience is considerably improved, and the retention period has been extended. My app is now a truly smart and handy fitness and health assistant. Next I'll show you how I managed to do this.

Integration Method

Registering as a Subscriber

Apply for the Health Kit service on HUAWEI Developers, select a product you have created, and select Registering the Subscription Notification Capability. You can select the HTTP subscription mode, enter the callback notification address, and test the connectivity of the address. Currently, the subscription capability is available to enterprise developers only. If you are an individual developer, you will not be able to use this capability for your app.

You can also select device-side notification and set the app package name and action if your app:

Uses the device-side subscription mode.
Subscribes to scenario-based goal events.
Relies on communications between APKs.

Registering Subscription Records

Send an HTTP request as follows to add or update subscription records:

POST
https://health-api.cloud.huawei.com/healthkit/v1/subscriptions

Request example

POST
https://health-api.cloud.huawei.com/healthkit/v1/subscriptions

Request body

POST
https://health-api.cloud.huawei.com/healthkit/v1/subscriptions
Content-Type: application/json
Authorization: Bearer ***
x-client-id: ***
x-version: ***
x-caller-trace-id: ***
{
  "subscriberId": "08666998-78f6-46b9-8620-faa06cdbac2b",
  "eventTypes": [
        {
            "type": "SCENARIO_GOAL_EVENT",
            "subType": "ACHIEVE",
            "eventType": "SCENARIO_GOAL_EVENT$ACHIEVE",
            "goalInfo": {
                "createTime": 1654660859105,
                "startDay": 20220608,  // Set the goal start date, which must be later than the date on which the goal is created.
                "recurrence": {
                    "unit": 1,  // Set the period unit to day.
                    "count": 30, // Set the entire period to 30 days.
                    "expectedAchievedCount": 28
                },
                "goals": [
                    {
                        "goalType": 1,
                        "metricGoal": {
                            "value": 10000, // Set the goal to 10,000 steps.
                            "fieldName": "steps",
                            "dataType": "com.huawei.continuous.steps.total"
                        }
                    }
                ]
            }
        }
    ]
}

Receiving Notifications of Goal Achievement

Send an HTTP request as follows to receive notifications of whether a goal is achieved:

POST
https://www.example.com/healthkit/notifications

Request example

POST
https://www.example.com/healthkit/notifications

Request body

POST
https://lfhealthdev.hwcloudtest.cn/test/healthkit/notifications
Content-Type: application/json
x-notification-signature: ***
[{
 "appId": "101524371",
 "subscriptionId": "3a82f885-97bf-47f8-84d1-21e558fe6e99",
 "periodIndex": 0,
 "periodStartDay": 20220608,
 "periodEndDay": 20220608,
 "goalAchieve": [{
  "goalType": 1,
  "metricGoal": {
   "value": 10000.0,
   "fieldName": "steps",
   "dataType": "com.huawei.continuous.steps.total"
  },
"achievedFlag": true // Goal achieved.
 }
    ]
}

(Optional) Querying Goal Achievement Results

Send an HTTP request as follows to query results of scenario-based events in a single period:

GET
https://health-api.cloud.huawei.com/healthkit/v1/subscriptions/3a82f885-97bf-47f8-84d1-21e558fe6e99/achievedRecord

Request example

GET
https://health-api.cloud.huawei.com/healthkit/v1/subscriptions/3a82f885-97bf-47f8-84d1-21e558fe6e99/achievedRecord

Response body

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[    
    {
 "openId": "MDFAMTAxNTI0MzcxQGQ0Y2M3N2UxZTVmNjcxNWFkMWQ5Y2JjYjlmZDZiaNTY3QDVhNmNkY2FiaMTFhYzc4NDk4NDI0MzJiaNjg0MzViaYmUyMGEzZjZkNzUzYWVjM2Q5ZTgwYWM5NTgzNmY",
 "appId": "101524371",
 "subscriptionId": "3a82f885-97bf-47f8-84d1-21e558fe6e99",
 "periodIndex": 0,
 "periodStartDay": 20220608,
 "periodEndDay": 20220608,
 "goalAchieve": [{
  "goalType": 1,
  "metricGoal": {
"value": 10000.0, // Goal value
   "fieldName": "steps",
   "dataType": "com.huawei.continuous.steps.total"
  },
"achievedResult": "20023", // Actual value
"achievedFlag": true // Flag indicating goal achieved
 }]
    },
    {
 "openId": "MDFAMTAxNTI0MzcxQGQ0Y2M3N2UxZTVmNjcxNWFkMWQ5Y2JjYjlmZDZiaNTY3QDVhNmNkY2FiaMTFhYzc4NDk4NDI0MzJiaNjg0MzViaYmUyMGEzZjZkNzUzYWVjM2Q5ZTgwYWM5NTgzNmY",
 "appId": "101524371",
 "subscriptionId": "3a82f885-97bf-47f8-84d1-21e558fe6e99",
 "periodIndex": 1,
 "periodStartDay": 20220609,
 "periodEndDay": 20220609,
 "goalAchieve": [{
  "goalType": 1,
  "metricGoal": {
   "value": 10000.0,  // Goal value
   "fieldName": "steps",
   "dataType": "com.huawei.continuous.steps.total"
  },
  "achievedResult": "9800",  // Actual value
  "achievedFlag": false // Flag indicating goal not achieved
 }]
    }
]

Conclusion

It is common to find apps that notify users of real-time fitness and health events, for example, for every kilometer that's run, or when the user's heart rate crosses a certain threshold, or when they have walked certain number of steps that current day.

However, health and fitness goals tend to be long-term, and can be broken down into small, periodic goals. This means that apps that only offer real time notifications are not as appealing as might otherwise be.

Users may set a long-term goal, like losing 10 kg in three months, or going to the gym and exercising three times per week for the upcoming year, and then break down the goal into one month or one week increments. They may expect apps to function as a reminder of their fitness or health goals over the long run.

Health Kit can help us do this easily, without requiring too much development workload.

This kit provides the scenario-based event subscription capability, empowering health and fitness apps to periodically notify users of whether or not they have met their set goals, in a timely manner.

With these notifications, app users will be able to keep better track of their goals, and be better motivated to meet them, or even use the app to share their goals with friends and loved ones.