API version 1.0

Introduction

Welcome to the WeFitter developer portal! 

The aim of this section is to offer you, the new developer, all the information required to successfully set up our API integration with your platform. It is important to acknowledge that WeFitter is undergoing continuous improvements and developments. Therefore, we are making all possible efforts to keep this document up do date.

Who are we?
Thunderbyte.AI is a full focused AI/ ML company building AI powered software products since 2009. At Thunderbyte.AI we work in an open, autonomous, informal and down-to-earth culture. Our office is located next to the Martini Hospital in Groningen. Within Thunderbyte.AI we work on many healthcare-related products. Our strength is working together on the basis of equality and improving each other.
WeFitter is an online service provider that enables apps and platforms to connect to well-known fitness apps and wearables. Lifestyle and health data collected from these wearable connections is combined with gamification elements such as challenges, leaderboards and point systems via WeFitter API. WeFitter helps apps and platforms implement the above components in order to collect valuable data and create more engagement on their platform. It is a product that will be potentially developed towards self-learning using artificial intelligence (AI) and machine learning. In this way, customers can create personalized and substantiated advice and journeys.

Let’s make IT fit!

Our terminology
Account = The account is the group of profiles that pertains to a client.
Admin = Administrator. The administrator is the client account manager/owner and is responsible for the client group profiles. The admin can modify and access the profiles and their data.

App = The app refers to the sub-group of profiles pertaining to an account. For example, the account usually covers the company, and the app can be a company department that is creating a group for fitness tracking and gamification. These apps can then be split further into teams.

Authentication = The process of accessing the WeFitter API. The authentication process involves receiving a ClientID and ClientSecret that are used to retrieve a bearer token. See Token below.

Bearer = Authentication token of three types. Basic (used to create administrator bearer tokens), administrator bearer tokens (for administrators) and profile bearer tokens (for logged-in profiles).

Challenge = Gamification feature of the WeFitter API. The challenge allows teams of profiles or individual profiles to compete against each other or to reach a specific goal.

Connection = Connections are the links between profiles and their wearables.

Notification = Send a notification to all devices for the specified profiles. The data will be sent to the client in a specific format.

Profile = Profiles are containers for wearables data. The profiles can be seen as an extension of users in a different system. Profiles are anonymous objects which can participate in teams and challenges. Keep in mind, listing profiles and creating profiles need an administrative bearer token, all profile specific actions need a separate bearer token that is returned after creating a profile. This bearer token is used in place of the administrative bearer token. (see profile create action for more information)

Push notification = Notification that is activated from the application and

SDK = Software Development Kit.

Team = A group of profiles that partake in the same activities, challenges and are usually related to or involved with the same client/organization.

Token = Before any calls can be made to WeFitter, BasicAuthentication is needed to verify the identity of the requesting party. This call will result into a Bearer token which has administrator privileges and is valid for one day (24 hours). This token can be used to create profiles, challenges, etc. The returned bearer is a JWT (JSON Web Token).

About the WeFitter API

WeFitter is a REST API that helps you retrieve, analyze, understand and leverage health data from end users. The API is comprised of two main components that are synergized to maximize the amount and quality of health data generated: health data integration (activity tracking apps & wearables) and gamification

The WeFitter API can support the data model generation based on an end user’s health data. Through a balanced blending of gamification and wearable data, the predictions on a person's health and lifestyle are made possible through the API. WeFitter is constantly evolving, thus aiming to create a perfect T-shaped model, where multiple wearables can be supported while offering a wide variety of data availability. 

API Components

Activity tracking wearables and apps

Today’s market of activity tracking wearables and apps available is continuously expanding. These apps and devices are used to collect various (health) information from their users, such as activity type, height, weight, sleep cycles, calories burned, stress levels and heart rate. The WeFitter API collects these data clusters from popular app and wearable brandsand stores them in a unified format, which you will benefit from once integrating the API.

If there is wearable or app not listed in our API package that you would be interested in, we are open to explore the possibilities of adding new connections. Please share your suggestion here!

Supported platforms overview

Wefitter is connected your Fitbit/Google/Withings/Garmin etc account, and not directly to the wearable itself. So in order for us to get data, the wearable needs to have synced with the provider (e.g. Fitbit, Google, etc.)
Wearables
Activities
Daily summary
Heart rate
Stress
Biometric
Sleep Summary
Google-Fit  
Healthkit  
Fitbit  
Garmin
Strava        
Withings  
Polar  
Data aggregation time
All the data that is retrieved from wearables and their respective provides is directly influenced by the provider. This is highly important when discussing update frequency. To be more specific for Fitbit, Strava, Withings and Polar, the update time is considered fast, as it works in an "event-driven" manner. Thus, when you complete a workout on Fitbit, WeFitter is directly notified that for the Fitbit wearable, there is new data that can be retrieved (pulled). On the other hand, for Googlefit, the data retrieval (pull) happens according to an interval. Therefore, WeFitter is bound by rate limits, resulting in less frequent updates.
 
Data deduplication
WeFitter makes use of data deduplication. Data deduplication is a process of eliminating data copies while decreasing storage capacity requirements. How does it apply to the WeFitter API? Since the WeFitter API connects to multiple wearables and apps, the client end-users might make connections with more than one platform.

This means that, while more than one platform tracks their activity, WeFitter collects the data from all platforms. These platforms might, in turn, collect the same data. The WeFitter API ensures that the data is collected in a unique numerical form, and that it is stored to portray an aggregate and complete tracking of the end-user’s activity.

In a practical example, data deduplication happens as such. A user tracks their activity using both GoogleFit and Apple Health simultaneously. The WeFitter API identifies the timestamps of the workout and inputs the data only one time. By this, the user can make use of multiple platforms for activity tracking, while having the most accurate results in the WeFitter API.

Note: At the moment, Strava is having a special case of deduplication that cannot be avoided in the current version of the API. If a user will do a training together with someone else, and both these users are tracking the activity at the same time, Strava considers it as two distinctive workouts.

Practical example: User A is doing a workout together with User B. Both Users are tracking the activity on Strava, to share it with their networks. User A tags User B in the post, and vice versa. Strava considers this as two separate workouts done by both User A, respectively User B. The WeFitter API will take both workouts in the overview.

Implementation

In this section, the implementation language is connected to the development platform Swagger. This document shows examples using Swagger, which is the interactive online environment. Therefore, all the terms used such as “click on execute” are Swagger-specific. The integration of the WeFitter API to your platform follows these steps:

  1. Authorization
  2. Profile creation
  3. Connection- To create a connection between your UI and the API
  4. Get data- To pull users data by using the proper endpoints.
  5. Implement Gamification
Authentication / Authorization

Authorization in the form of Bearer and Profile token are needed to perform actions in the API.

The flowchart below shows the steps you will perform when going through the authorization stage. You (your organisation) have received a ClientID and a ClientSecret. With your ClientID and ClientSecret, you can create an administrator bearer that you need to authorize most API calls. For authorization of API calls for public profiles you need a profile bearer, which is described later in this section.

Note: It is important to keep your ClientId and ClientSecret secure and safe. These credentials cannot be retrieved at a later stage.

Bearer types and authentications

The WeFitter API uses distinctive authorizations for different functions. The first authentication type is the Basic Authentication, which is used to create administrator bearer tokens. Once a bearer token has been made, remove this authentication (for the Swagger environment, you need to ‘log out’).

Security Scheme Type 

HTTP

HTTP Authorization Scheme 

basic

Group

API Call

Authentication

Token

Create Token

Basic

The second authentication type is Bearer Authentication for administrators. When using the GUI, please don't forget to prefix your bearer tokens with the text 'bearer', followed by a space. It is important to note the fact that the Admin Token key is available for only 24 hours. After this time limit, you will have to requesta new token. 

Security Scheme Type 

API Key

Header parameter name:

Authorization

Group

API Call

Authentication

Profile

Create Profile

BearerAdmin

Profile

Create Event

BearerAdmin

Challenge

Create Challenge

BearerAdmin

Challenge

Edit challenge

BearerAdmin

Challenge

Partial edit challenge

BearerAdmin

Challenge

Delete challenge

BearerAdmin

Challenge

Add members

BearerAdmin

Challenge

Add members

BearerAdmin

Challenge

Remove members

BearerAdmin

Team

Add members

BearerAdmin

Team

Add members

BearerAdmin

Team

Remove members

BearerAdmin

The third authentication type is the Bearer Profile authentication. This is used for logged-in profiles. When using the GUI, please don't forget to prefix your bearer tokens with the text 'bearer', followed by a space.

Security Scheme Type 

API Key

Header parameter name:

Authorization

Group

API Call

Authorizations

Profile

Activity Segment

BearerProfile

Profile

Bio Metric

BearerProfile

Profile

BMI

BearerProfile

Profile

Daily Summary

BearerProfile

Profile

Daily Summary Sample

BearerProfile

Profile

Event

BearerProfile

The WeFitter API uses specific authentication types for specific API calls. However, there are some calls that can be made using either the Bearer Admin credentials or the Bearer Profile authentication. The same advice of using the GUI is applicable, therefore make sure not to forget to prefix your bearer tokens with the text 'bearer', followed by a space.

Group

API Call

Authorizations

Profile

List Profiles

(BearerAdmin) OR (BearerProfile)

Profile

Delete Profile

(BearerAdmin) OR (BearerProfile)

App

Totals

(BearerAdmin) OR (BearerProfile)

Challenge

List Challenges

(BearerAdmin) OR (BearerProfile)

Challenge

Team learderboard

(BearerAdmin) OR (BearerProfile)

Challenge

Team contribution

(BearerAdmin) OR (BearerProfile)

Challenge

Get challenge

(BearerAdmin) OR (BearerProfile)

Challenge

Leaderboard

(BearerAdmin) OR (BearerProfile)

Challenge

Add member

(BearerAdmin) OR (BearerProfile)

Challenge

Add member

(BearerAdmin) OR (BearerProfile)

Challenge

Remove member

(BearerAdmin) OR (BearerProfile)

Challenge

Get members

(BearerAdmin) OR (BearerProfile)

Challenge

Periods

(BearerAdmin) OR (BearerProfile)

Team

List teams

(BearerAdmin) OR (BearerProfile)

Team

Create team

(BearerAdmin) OR (BearerProfile)

Team

Team

(BearerAdmin) OR (BearerProfile)

Team

Edit team

(BearerAdmin) OR (BearerProfile)

Team

Partial edit a team

(BearerAdmin) OR (BearerProfile)

Team

Deletes a team

(BearerAdmin) OR (BearerProfile)

Team

Add member

(BearerAdmin) OR (BearerProfile)

Team

Add member

(BearerAdmin) OR (BearerProfile)

Team

Remove member

(BearerAdmin) OR (BearerProfile)

Generating the administrator bearer

Initiate Swagger on https://api.wefitter.com/api/v1.1/swagger and press the Authorize button. This will lead you to a pop-up window. Enter your CientID as Username and ClientSecret as Password and press the upper green Authorize button. Then press Close.

Now, you need to create the token (administrator bearer). 

 

Go to POST /token/ Create token and click the button Try it out. Next, click on Execute.

By completing this action, you will get a result including the administrator bearer. The administrator bearer is listed in the response body.

Now, you need to copy the bearer to the clipboard. This will be used in the next steps.

 

You need to scroll to the top and press Authorize to popup the window, following the next steps:

  • Logout from Basic Authorization
  • In the Bearer (apiKey) Value field write ‘Bearer’ plus space + the bearer you copied to the clipboard
  • Press Authorize.

You will now be able to access all API which need this administrator bearer for authorization.

A practical example:

List Profiles: what you see before and after you make the call in Swagger

Here you can find the correlating documentation on https://api.wefitter.com/api/v1.1/redoc/

Profile

Creating the profile

This function will allow you to create, access and model the profile(s) of the users.You need the administration bearer to create a new profile. Note that the response of creating the profile give you a bearer: the profile bearer. This profile bearer is generated when the profile is created, and you need to store this bearer as it can NOT be retrieved later anymore.

In the illustrations below, you can see a practical example of the API call with an example bearer.

In order to access the profile, you need to put the profile bearer in the Authorization window.

Copy the bearer from the response, scroll to the top and press Authorize to open the Authorization window, press logout and then put the word ‘bearer’ followed by a space and followed by the profile bearer in the box. Then press Authorize.

Accessing the profile

Now you have access to the public profile.

Read the profile as follows: Press ‘try it out’, fill in the public_id from the profile (see response from profile creation).

Connections

The next step in the integration process is to make a connection with the wearable devices. The calls can be used for both the App and the Web application. The main difference to be noted is that it’s a predefined piece of HTML or Json data. The Json response is the preferred and most flexible way of working with the WeFitter App Connections

The above image is an example from the WeFitter demo App.

In the process below, we will demonstrate on how you can get the backend calls for this screen.

How to:

1) Use the ‘profile bearer’

2) Go to GET/profile/{public_id}/connections/, press the button Try it out.

3) Press Execute and you will get the following: The profile bearer is listed in the response body.

4) In the response, you can see the URLs for different connections. Test one of the URL. It is important to note the redirect parameter, which allows the API call to return a redirection to the specified URL for the connection.

5) You can use each of these URL to implement in the connection screen.

 

Web application connections

If you are using a web application, please follow the following steps.

1) Use the ‘profile bearer’.

2) Go to GET/profile/{public_id}/connection_widget/ press the button Try it out.

3) You can test the URL and use them to implement the connection screen.

 

Connecting with Apple Health

We provide an SDK to make a connection with Apple Health. Hence, it is only possible to make a connection of Apple Health with a mobile application and not with a web application.

Please contact api-support@wefitter to provide you with the SDK kit. The instructions are attached in the zip file that we share with you.

Connecting with Samsung Health

We also provide an SDK to make a connection with Samsung Health. Therefore, similar to the Apple Health connection, it is only possible to make a connection of Samsung Health with a mobile application and not with a web application.

Please contact api-support@wefitter to provide you with the SDK kit. The instructions are attached in the zip file that we share with you.

Pull data

If you want to have data pushed from the wearable/app, please go to the Webhooks section.

The API provides the way to pull the data of the users. The data is always raw, however logical representation in form of graph can be made from the available data.

Raw data, in this context, refers to the data that is not collected and aggregated by WeFitter directly, buy is collected after the aggregation process of another app or wearable.

To give you a better insight of the function, we would like to present some practical examples.

Implementation example 1: The adjacent graph shows information like step counts, distance tracked and workouts for a particular day.

To pull such information, you can follow the steps below:

Steps:

1) Use the ‘profile bearer’ and make sure it is authorized.

2) Get the workout - UseGET/profile/{profile_public_id}/workout/, press the button Try it out. Fill in the public ID for certain profile. You can filter on the start_date and end_date to filter on different dates.

3) In response, you will see the list of workouts performed by the profile.

4) You can implement this response to show list of workouts per specific date

5) Get daily summaries - Use should use GET/profile/{profile_public_id}/daily_summary/

Daily Summary. Press the button Try it out. Fill in the public ID for certain profile.

6) The response will provide you with daily summary of an user based on each day.

 

Implementation example 2:

Another way in which data can be showed is through graphs that monitor daily, weekly and monthly progress for distance, calorie counts, step counts and workous.

 

Steps:

1) Use the ‘profile bearer’ and make sure it is authorized.

2) Get the workout - UseGET/profile/{profile_public_id}/workout/, press the button Try it out. Fill in the public ID for certain profile. You can filter on the start_date and end_date to filter on different dates

Here, you can insert an enddate and start date, and you can also limit the responses on page size.

3) In response, you will see the list of workouts performed by the profile.

4) You can implement this response to show list of workouts per specific date.

5) Get daily summaries - Use should use GET/profile/{profile_public_id}/daily_summary/

Daily Summary. Press the button Try it out. Fill in the public ID for certain profile.

One of the parameters here is the cursor, which is the pagination value (page number). The page size allows the limitation of return values.

6) The response will provide you with distance, steps, calories of a user based on each day. You can create a graph using these values.

Example body: {

"date": "2021-02-02",

"distance": 3178.550847053528,

"steps": 3966,

"calories": 2051.5490168399406,

"points": 0,

"source": "GOOGLEFIT",

"heart_rate_summary": null,

"stress_summary": null

},

 

Push data

The push data "push endpoint" function is applicable only for API clients.

API clients can use the push endpoints to fill in an endpoint URLs of their own enpoints (picture below) in order to get specific data pushed. The version field determines how the selected data is being serialized, mirroring the API data model.

The push endpoint can be accessed through the WeFitter Dashboard, as part of the App definition tab. For more information, please consult the Dashboard Guide.

Note: it is important to understand the role of data deduplication in the Push Data stream. As the data is pushed from the moment it is available throuh the WeFitter API, the same workout from multiple connections might be pushed. The client will receive two workouts, but, from that moment onwards, the WeFitter API has the ability to deduplicate.

Gamification API

The greatest task of today’s world is promoting health solutions. Motivating users to engage in a healthier lifestyle is not a simple task and can sometimes be quite a to maintain their engagement and motivation. Through integrating our API, the solution can fall right in your hands.

The WeFitter API features a framework to make a user’s experience more dynamic, interactive and engaging through gamification. This is achieved through the implementation of the challenge framework. We provide several different challenge types like team, individual and streak challenges. With the creation of challenges, individuals or teams can participate in a set goal or be the highest on the leaderboard before time runs out.

The parameters for these challenges can be set to distance, kcal, time, step counts and points. The points are generated based on the other metrics, respectively distance, kcal, time or step counts, according to your preferences. Within the API, individual leaderboards and teams to show progress on these parameters are also provided.

Our API offers all the tools to create a fully gamified experience for end users to win rewards, be motivated and remain engaged!

Although the challenges presented are categorized as individual, team and global, the client and API user have the possibility to explore and create own challenges or use predefined challenges that can be found in the API Swagger environment.

Challenge parameters

The WeFitter API allows its clients and users to explore and experiment with gamification through numerous challenge types. Below, a table presenting information on the challenge components, such as types, goal, visibility, description, calculation method, enrolment method and repetition.

Type

Individual - An individual challenge type is a challenge in which the user is participating separately from the rest of the participants (goal or leaderboard set-up possible)

Team - A team challenge type is a challenge in which the user is participating with team members against other teams. All individual progress of the team will be accumulated (goal or leaderboard set-up possible)

Global - A global challenge type is a challenge in which the user is participating with all other participants. All indiviodual progress will be accumulated (goal or leaderboard set-up possible)

 

Goal

Daily - A goal which is repeated daily over the time of the challenge

Total - A goal which is the total goal over the time of the challenge

Weekly - A goal which is repeated weekly over the time of the challenge

Monthly - A goal which is repeated monthly over the time of the challenge

None/leaderboard - No goal means that the challenge is going into a leaderboard set-up, where users have to achieve the highest position in the leaderboard before the time of the challenge runs out

 

Description

Description text of the challenge.

Visibility

Public - The challenge is visible for every participant/member in the same App.

Private - The challenge is only visible to the pre-enrolled users in the App.

 

Calculation method

Sum - The sum challenge calculation will be a summation of all individual, team or global data.

Average - The average challenge calculation will be the average of all individual, team or global data.

 

Enrolment method

Automatic - Users will be enroled automatically

Manual - Users will be enroled manually

 

Repetition

None - No repetition

Streak - Challenge goal (daily, weekly, monthly) achievements will be calculated in the leaderdboard every time the goal is hit

Stick to it - Challenge goal (daily, weekly, monthly) achievements will be calculated in the leaderdboard every time the goal is hit repeteadly

 

Overview of data sources and connections supported

To offer the full visibility of our API frameworks, the WeFitter API data model will be made available on our developer portal. Until the launch of our new developer portal, if you wish to have access to our data model, please make your request at tech@wefitter.com

 

API Gamification

The API allows the admin to create different kind of challenges for their user, hence giving a touch of competition for better health of the users. In this section, the three major challenge types are presented. For the full list of possibilities, please go to the Other challenges section.

Further, each challenge is divided in two different stages:

1) The steps you need to take to create these challenges

2) Visual appearance of these challenge in an App.

 

Creating a team

For participating in the team challenge, it should be mandatory for the users to join a team. Hence it is good to have this procedure in the onboarding of the App.

For reference we are showing the implementation of this feature in the WeFitter App. In the image, you can see the option to:

  • Create a new team
  • Add a member in a team
  • By unpicking the team, a user can leave a team

1) Create a new team

USE POST/team/Create Team and press on try it out. Please fill in the mandatory fields for successful execution

ii) The response provides you with the team ID(Public_ID) of the team.

2) Add a member in a team

USE POST/team/{public_id}/member/ and press on try it out. Fill in the mandatory fields like teamID(public_id) of the team which needs an addition and the Profile_ID of the profile which needs to be added.

The response confirms the addition of the profile

3) Leave the team

USE DELETE/team/{public_id}/member/ and press on try it out. Fill in the mandatory fields like teamID(public_id) of the team which needs a deletion and the Profile_ID of the profile which needs to be deleted.

The response confirms the deletion of the profile

 

Team goal challenge

In this challenge, the teams try to compete with each other to reach a common goal. 

How to:

The image below is from the dashboard of WeFitter. You can login to the dashboard using https://api.wefitter.com/dashboard/login/. The dashboard provides an easy way to organize different challenges.

However, the API provides another method to create challenge. The image shows the field that needs to be filled to create a team challenge with 10 km goal

You need to use ‘Admin bearer token’ to create a challenge.

Use POST/challenge/Create challenge to create the challenges. Press the button Try it out. Fill in the information for the challenge

Note: In order to keep the challenge on ‘daily summary’ you should skip the activity field altogether.

 

App visual appearance

 Use the endpoint  GET/challenge/{public_id}/Get Challenge to get the challenge that you want to implement.

Note: The value of the goal_progress field will depend on which bearer token is used.

 The information that appears in the screen above is illustrated below.

"title": "Dashboard change  test 2",

"slogan": "use the slogan",

 "start": "2021-01-01T00:00:00Z",

 "end": "2021-10-31T00:00:00Z",

"type": "TEAM",

"description": "description",

"enrollment_method": "MANUAL"

     

Challenge enrollment

This section explains how to enable the user enrollment to the challenge.

The challenge screen shows ‘JOIN’ button. Hence this is a manual enrollment challenge. Manual enrollment means that the user will have to enroll themselves. Automatic enrollment of challenge happens when the users are automatically made to participate in a challenge. Hence, they are not given an option to join a challenge, although they can leave a challenge.

For JOIN button, you should use post/challenge/{public_id}/member/. Hence when a user clicks on ‘JOIN’, they get enrolled in the challenge.

For LEAVE, you should use delete/challenge/{public_id}/member/  (Please refer Create team section for more information)

Note: a team is not mandatory. The programme picks the first team (more information in the FAQ). Teams are independent objects that live on its own. So, they are independent of challenges.Note: The value of the goal_progress field will depend on which bearer token is used.

Practically, an individual can be a member of Team A. Then, if there is a team challenge that the individual wants to compete in, they have the ability to enroll into the challenge with one of teams they are a member of. Therefore, to join a team challenge, the individual needs to be part of a team. If a profile is a member of multiple teams, and no team is specific in the call that enrolls the user in the challenge, then the first team gets automatically picked.

 

Challenge progression 

For getting the progress of the challenge and more related information, you need to get the information about the ongoing challenge.

Use GET/challenge/{public_id}/Get Challenge to get the challenge that you want to view. Press the button Try it out and insert the public ID.

The response of the call consists the progress of the challenge along with other information.

Tip: The goal progress circle is a based on = (Total goal- Progress) / Number of days left in the challenge

   "url": "https://beta.wefitter.com/api/v1.1/challenge/b96c7271-c61c-4718-aa69-e46b94e360c4/",

   "public_id": "b96c7271-c61c-4718-aa69-e46b94e360c4",

 "title": "Test challenge",

 "slogan": "",

  "start": "2021-03-01T00:00:00Z",

  "end": "2021-03-31T00:00:00Z",

  "type": "Team",

  "goal": "TOTAL",

  "goal_value": null,

  "goal_type": "STEPS",

  "visibility": "PUBLIC",

  "num_members": 0,

  "description": "",

  "calculation_method": "SUM",

  "goal_progress": 0,

  "enrollment_method": "MANUAL",

  "members": [],

  "repetition": "NONE",

  "avatar": null,

  "data_source": "dailysummary",

  "activity_types": [],

  "total_calories": 0,

  "total_distance": 0,

  "total_steps": 0,

   "total_points": 0,

  "total_activity_duration": "P0D"                     

}

 

Challenge leaderboard 

The last component in the challenge visualization is the leaderboard (scoreboard) of the challenge. Below, a practical visualization of the ranking of all teams is shown. 

For this, Use get/challenge/{public_id}/leaderboard/ and press on try it out. Make sure you have proper authorization.

Using this call, you will be able to use to get the response that shows the team leaderboard (scoreboard).

Contribution screen

The contribution screen in the team goal challenge shows the contribution each member has made in reaching the goal.

Use GET/challenge/{challenge_public_id}/team/{team_public_id}/ to get the contribution of team members. Press on try it out.

You will need to fill in the Challenge_public_id and team_public_id for which you want to see the contribution

The team_public id can be obtained from the response screen of scoreboard (image). 

Now use the response of the call and implement it in the contribution screen of team challenge.

Global goal challenge

In this challenge, the individual tries to reach a common goal on a global scale. 

How to:

The image below is from the dashboard of WeFitter. You can login to the dashboard using https://api.wefitter.com/dashboard/login/. The dashboard provides an easy way to organize different challenges.

However, API provides another method to create challenge. The image shows the field that needs to be filled to create a team challenge with 10 km goal.

You need to use ‘Admin bearer token’ to create a challenge.

Use POST/challenge/Create challenge to create the challenges. Press the button Try it out. Fill in the information for the challenge.

 Note: In order to keep the challenge on ‘daily summary’ you should skip the activity field altogether.

App visual appearance

 Use the endpoint  GET/challenge/{public_id}/Get Challenge to get the challenge that you want demonstrate and use the highlighted fields in the App implementation.

  "public_id": "3e62369d-4f99-4169-9ae1-757abb953adf",

  "title": "Dashboard change  test 2",

  "slogan": "use the slogan",

  "start": "2021-01-01T00:00:00Z",

  "end": "2021-10-31T00:00:00Z",

  "type": "GROUP",

  "description": "description",

  "enrollment_method": "MANUAL",

 

Challenge enrollment

This section explains how to enable the user enrollment to the challenge.

The challenge screen shows ‘JOIN’ button. Hence this is a manual enrollment challenge. Manual enrollment means that the user will have to enroll themselves. Automatic enrollment of challenge happens when the users are automatically made to participate in a challenge. Hence, they are not given an option to join a challenge, although they can leave a challenge.

For JOIN button, you should use post/challenge/{public_id}/member/. Hence when a user clicks on ‘JOIN’, they get enrolled in the challenge. 

For LEAVE, you should use delete/challenge/{public_id}/member/ 

 

Challenge progression 

For getting the progress of the challenge and more related information, you need to get the information about the ongoing challenge.

Use GET/challenge/{public_id}/Get Challenge to get the challenge that you want to view. Press the button Try it out and insert the public ID.

The response of the call consists the progress of the challenge along with other information. The underlined fields are used in the ‘progression screen’

Note: ‘GROUP’ here is a term used for ‘GLOBAL’

Tip: The goal progress circle is a based on = (Total goal- Progress) / Number of days left in the challenge

   "url": "https://beta.wefitter.com/api/v1.1/challenge/3e62369d-4f99-4169-9ae1-757abb953adf/",

  "public_id": "3e62369d-4f99-4169-9ae1-757abb953adf",

  "title": "Global Challenge",

  "slogan": "Text for Slogan",

  "start": "2021-01-01T00:00:00Z",

  "end": "2021-10-31T00:00:00Z",

  "type": "GROUP",

  "goal": "MONTHLY",

  "goal_value": 200000,

  "goal_type": "DISTANCE",

  "visibility": "PUBLIC",

  "num_members": 51,

  "description": "",

  "calculation_method": "SUM",

  "goal_progress": 542794.3597489496,

  "enrollment_method": "AUTOMATIC",

  "members": [

    { 

      "url": "https://beta.wefitter.com/api/v1.1/profile/66f90460-d4c1-4960-86f7-c5469a200b64/",

      "public_id": "66f90460-d4c1-4960-86f7-c5469a200b64",

      "name": "generated_profile_0",

      "gender": null,

      "team": null,

      "reference": ""

In this example, the goal_progress parameter is shown from the perspective of the requesting user.   

Challenge leaderboard 

The last component in the global challenge visualization is the leaderboard (scoreboard) of the challenge.

For this, Use get/challenge/{public_id}/leaderboard/ and press on try it out. Make sure you have proper authorization. 

Use the response to show in the Global scoreboard.

 

Individual challenge

In this challenge, the individual tries to reach a common goal.

How to: 

 

The image below is from the dashboard of WeFitter. You can login to the dashboard using https://api.wefitter.com/dashboard/login/. The dashboard provides an easy way to organize different challenges.

However, API provides another method to create challenge. The image shows the field that needs to be filled to create an Individual challenge of 3,5 km goal with daily repetition. This means that, the goal gets refreshed every day.

 

You need to use ‘Admin bearer token’ to create a challenge.

Use POST/challenge/Create challenge to create the challenges. Press the button Try it out.

Fill in the information for the challenge.

Note:  In order to keep the challenge on ‘daily summary’ you should skip the activity field altogether.

Example code (based on the image of dashboard):

 

{

  "title": "Individual Challenge",

  "slogan": "Individual goal Challenge",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "INDIVIDUAL",

  "goal": "DAILY",

  "goal_value": 3500,

  "goal_type": "STEPS",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "STREAK",     or    "STICK TO IT"

  "avatar": "string",

  “activity type” : “walking”

}

App visual appearance

 This screen shows several different kinds of information. The endpoints to get this information is:

Use the endpoint  GET/challenge/{public_id}/Get Challenge to get the challenge that you want to implement.

The information that appears in the screen on the right side is illustrated below.

 

  "title": "Testing individual points challenge",

 "slogan": "Dashboard change  test 1",

 "start": "2021-02-28T23:00:00Z",

 "end": "2021-03-31T10:00:00Z",

 "type": "INDIVIDUAL",

 "goal": "DAILY",

 "goal_value": 3500,

 "goal_type": "STEPS",

 "visibility": "PUBLIC",

  "description": "",

  "calculation_method": "SUM",

  "goal_progress": 0,

  "enrollment_method": "AUTOMATIC",

  "members": [

    {

      "url": "https://beta.wefitter.com/api/v1.1/profile/66f90460-d4c1-4960-86f7-c5469a200b64/",

      "public_id": "66f90460-d4c1-4960-86f7-c5469a200b64",

      "name": "generated_profile_0",

      "gender": null,

      "team": null,

      "reference": ""

    } 

 

The graph in the screens show the history of the user. The goal has a ‘daily repetition’. Hence, the goal has to be reached daily.

To show the history of the person, Use GET/challenge/{public_id}/leaderboard_history/

The response shows the leaderboard based on repetition. In case of daily, if will show daily progress in the past. If the repetition is on weekly, then it will show weekly progress that was made in the past by the profile.

Stick to it and Streak Challenge

Stick to it

When you put the challenge on Stick to it, then the score of the challenge shows the total number of days a user has reached the goal. In the image of the screen, this is demonstrated as 53/68 days.

Streak

When you put the challenge on Streak then the score of the challenge shows the longest streak when a person reached the goal. For example, in the image of the App, the longest streak is 15 days. Hence the user completed the goal on 15 consecutive days.

To implement these features, use GET/challenge/{public_id}/leaderboard/ and enter Try it out.

The response will give the score of the user. This is the streak/stick to it score (Based on the type of challenge you have put in ‘Create Challenge’)

 

Other challenges set-ups

 There are more kinds of challenges possible via the API. Hence, here is the overview of the challenge.

Challenge Create Challenge Example body
Team leaderboard Challenge

  "title": "Team leaderboard Challenge",

  "slogan": "Team leaderboard Challenge",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "TEAM",

  "goal": "TOTAL",

  "goal_value": (delete this field)

  "goal_type": "DISTANCE",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "NONE",

  "avatar": "string",

Individual leaderboard Challenge

  "title": "Individual leaderboard Challenge",

  "slogan": "Individual leaderboard Challenge",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "INDIVIDUAL",

  "goal": "TOTAL",

  "goal_value": (delete this field)

  "goal_type": "DISTANCE",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "NONE",

  "avatar": "string",
Global leaderboard Challenge

  "title": "Global leaderboard Challenge",

  "slogan": "Global leaderboard Challenge",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "GROUP",

  "goal": "TOTAL",

  "goal_value": (delete this field)

  "goal_type": "DISTANCE",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "NONE",

  "avatar": "string",

Team Stick to it

"title": "Team Stick to it",

  "slogan": "Team Stick to it",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "TEAM",

  "goal": "DAILY",

  "goal_value": 13500,

  "goal_type": "STEPS",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "STICK TO IT"

  "avatar": "string",

  “activity type” : “walking”
Global Stick to it

"title": "Global Stick to it",

  "slogan": "Global Stick to it",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "GLOBAL",

  "goal": "DAILY",

  "goal_value": 13500,

  "goal_type": "STEPS",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "STICK TO IT"

  "avatar": "string",

  “activity type” : “walking”

Team Streak

"title": "Team Streak",

  "slogan": "Team Streak ",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "TEAM",

  "goal": "DAILY",

  "goal_value": 13500,

  "goal_type": "STEPS",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "STREAK"

  "avatar": "string",

“activity type” : “walking”

Global Team Streak

"title": "Global Team Streak",

  "slogan": "Global Team Streak",

  "start": "2021-03-01T13:05:11.467Z",

  "end": "2021-03-31T13:05:11.467Z",

  "type": "GLOBAL",

  "goal": "DAILY",

  "goal_value": 13500,

  "goal_type": "STEPS",

  "visibility": "PUBLIC",

  "description": "Describe the cause of the challenge",

  "calculation_method": "SUM",

  "enrollment_method": "MANUAL",

  "repetition": "STREAK",  

  "avatar": "string",

  “activity type” : “walking”

Points

 Some challenges may allow for point definitions. This requires a defined point model that you want for a specific app. This allows you to attribute points for a single minute, km, step or kcal. For now the point definition model is only working for ‘’other’’, which will support all activity types. In a next version you will be able to make point models for specific activity types. Below, the dashboard view of point definitions is illustrated.

Webhooks

The Webhooks are used to give real-time status updates, for example when someone has completed the challenge. You need to use a URL to push these statuses. After implementation of the push endpoints, you will get a ping every time a status has changed. You can use these pings to send a notification to a user about his/her status.

Set-up:

1) You log into the dashboard- https://api.wefitter.com/dashboard/login/ and access your App.

2) Inside the App, you can select the option of 'push endpoints'

3) Select data type, you can select V1. Save them individually (see screenshot) with a callback URL.

4) Tick the box for ‘Active’ status.

5) Notifications are sent with an interval of 5 minutes.

Types of Webhooks @WeFitter

1) When new ‘activity’ data is available

2) When status of the profile has changed in the challenge.

 

New activity for a profile

When new activity data is available, you will receive a status. Directly pushing incoming data (workouts, daily summaries etc.)   

a) Activity

b) Biometric

c) Daily summaries

d) Heartrate data

e) myzone workout

f) Sleep summary

g) Stress sample

h) Stress summary

 

 

Example body:

{"profile": "aaaaaav-afb0-gggggggff", "data": {"timestamp": "2021-02-09T13:32:59Z", "duration": "00:33:30.914000", "source": "POLAR", "is_manual": null, "type": "WALKING", "distance": 449.0, "steps": null, "calories": null, "points": 33.51}

 

Status change of profile in challenge

Besides to directly pushing incoming data (workouts, daily summaries etc.) we currently provide the following webhook notifications:

CHALLENGE_START
CHALLENGE_END
PERIOD_GOAL_REACHED
PERIOD_GOAL_PARTIALLY_REACHED

Note that the last two are currently only supported for Individual challenges and not Team or Group (global). We are working on the implementation for these types.

You can register an endpoint to receive webhook notifications in the WeFitter dashboard, by creating push endpoints on the corresponding tab on the app-edit page, e.g.

https://api.wefitter.com/dashboard/account/{account_id}/app/{app_id}/

Notifications are sent with an interval of 5 minutes.

Challenge start and end

Challenge start example body (similarly for challenge end, but event is 'challenge_end'):
{
"event":"challenge_start",
"event_timestamp":"2021-02-17 15:39:00+01:00",
"challenge_id":aaaaaa-0000-bbbb-cccc-dddddd4d",
"challenge_title":"foo"
}

Period goal reached example body

This notification is sent each time a profile completes the goal for the current challenge period (e.g. a given day, week, month or total challenge duration, depending on challenge type).

{
"event":"challenge_period_goal_reached",
"challenge_id":"aaaaaa-0000-bbbb-cccc-dddddd4d",
"challenge_title":"foo",
"period_start":"2021-02-17 14:39:00+00:00",
"period_end":"2021-02-18 14:39:00+00:00",
"model":"profile",
"model_id":"aaaaaa-0000-bbbb-cccc-dddddd4d"
}

Period goal partially reached

Example body:

{
"event":"partial_period_goal_reached",
"challenge_id":"aaaaaa-0000-bbbb-cccc-dddddd4d",
"challenge_title":"foo",
"period_start":"2021-02-17 14:39:00+00:00",
"period_end":"2021-02-18 14:39:00+00:00",
"model":"profile",
"model_id":"aaaaa- vvvv-eeee-aaaaaaaaa",
"goal_reached_proportion":0.80321,
 "current_score":481.926
}

This notification is sent each time a profile partially completes the goal for the current challenge period (e.g. a given day, week, month or total challenge duration, depending on challenge type).

Triggers for this notification are reaching 25%, 50% and 75% of the goal value in the current period. If a profile receives a new score (through daily summaries, workouts, or events) and the new score crosses multiple thresholds (e.g. 25% and 50% at the same time), we only send one notification.

 

Events

The WeFitter API offers the possibility to implement the events endpoints for achieving goals that go beyond physical activity. 

Example: "Eat your vegetables challenge" 

The client wants to put a challenge where they ask the user if he/she had 2 vegetables/Fruits a day.

Frontend design

The developer needs to create a screen where the question pops ups. "Did you eat your veggies?" with the answer option "Yes? No?"

When the user clicks on Yes, an event is created, and points are added on the leaderboard.

Hence, on clicking on ‘yes’ or a + sign should trigger an event.

For more information, please refer to https://api.wefitter.com/api/v1/redoc/#operation/profile_event_create

 

Creating the challenge on the dashboard

The challenge can be created as follows: 

  • Points gained from events are normally added to a challenge, hence you need create a challenge where no other points are added except points from Events.
  • That is the same reason I have kept the challenge on ‘Yoga’. Please use a ‘activity type’ which is not a part of an ongoing challenge or else the challenge will show more points (activity points + events points)
  • Keep the point definition of this activity on 0. (0+ Event points= Event points)
  • Now only points from ‘Events’ will get added to users who are participating in this challenge.

Note: Points definitions are now set on app-level. In the future, we are aiming for configurations per challenge.

 

In short:

1) Make point definition for yoga (or any other activity that is not being used in a challenge) as 0(see screenshot).

2) Use the 'create Event' and implement it on the frontend (ex- Did you eat your veggies?). When a person clicks on yes then an event should be created.

3) Create a challenge like shown in the attachment.

4) Now the challenge will only count the points gained from the 'events endpoint'. You can implement the scoreboard of this challenge.

Note: Points definitions are now set on app-level. In the future, we also want it to be able to configure per challenge.

Second implementation

The developer needs to create a screen where the question pop ups.

"Did you eat your veggies?"  Yes? No?

By clicking on ‘yes’, an event is created, and points are added to the profile.

Now using using GET Profile, total_points (https://api.wefitter.com/api/v1/redoc/#operation/profile_read) you can get the total points of the profiles.

You can create a filter on events and sum it on profile level. This will provide you the total of the event points per profile.

Important to know: workouts and daily summaries have heart rate information attached to them, (from version 1.1 onwards.)

Thank you for reaching out!

We will be in touch with you soon.
WeFitter team.
footer_bg