Skip to main content
Version: v3+

Quick Start

Intro​

This article will demonstrate how to create, develop, and test a Zepp OS Workout Extension application through a complete example.

Before we begin, let me introduce some relevant background：

info
  • Workout Extension can only be used on devices with API_LEVEL 3.6 or above
  • Workout Extension has the capabilities of most JS APIs, but there are some limitations. For details, please refer to API restrictions
  • Workout Extension is an independent application with an independent appId. It needs to be created, submitted, and reviewed in the developer background before it can be launched on the app store
  • Users can configure to run multiple Workout Extensions simultaneously

Basic process​

1. Environmental preparation​

The development process of "Workout Extension" is the same as that of Zepp OS Mini Program, and the required power builder is the same. Please refer to Environment Preparation to complete the environment preparation.

2. Create project​

In the process of creating a project, we directly use the zeus create workout-sample command of the Zeus CLI tool to create a "Workout Extension" template project. Select the project type as WORKOUT_EXTENSION.

note

Please install the latest version of Zeus CLI using npm i @zeppos/zeus-cli -g before executing the command

3. Run in simulator​

This step-by-step process is consistent with the Zepp OS Mini Program. Refer to Running Simulator to complete the installation and operation of the emulator.

Use the Terminal to enter the newly created "Workout Extension" directory, execute the zeus dev compile preview command, and we can see our workout extension application in the Simulator.

info

For the convenience of developers, the Workout Extension is displayed in the application list in the emulator, and the real machine needs to be added in the workout application (not displayed in the application list).

4. Preview on a Watch​

This development process is consistent with the Zepp OS Mini Program. Refer to Preview on a Watch to complete the real machine preview.

Relevant points​

  • DataWidget Construction function
  • SPORT_DATA widget
    • The SPORT_DATA widget is an API specially designed for "Workout Extension", with rich data item display types, which can achieve real-time display of sports data
  • getSportData
    • The getSportData interface can obtain real-time data of sports applications, and developers can process and record the data

app.json​

Please refer to Mini Program Configuration for app.json.

The difference between Workout Extension is only in the configuration of the module field, where data-widget represents the Workout Extension configuration.

info

"Workout Extension" can only be used on devices with API_LEVEL 3.6 or above, and "minVersion" needs to be configured to 3.6.

The widgets field is an array with a maximum length of 1. This means that in a Workout Extension application with the same appId, up to 1 Workout Extension plugin can exist simultaneously (multiple plugins may be supported later).

"module": {
  "data-widget":{
    "widgets": [{
      "path": "pages/plugin1",
      "name": "plugin2",
      "icon": "icon2.png",
      "runtime": {
        "ability": [{
          "type": 1,
          "subType": [1, 2, 3]
        }]
      }
    }]
  },
}
PropertiesTypeDescription
typenumberCurrently, only 1 can be filled in, representing the "Workout Extension" type
subTypeArray<number>Supported sports types, an empty array [] represents support for all sports types, for the meanings of other sports types, please refer to the subType sports types at the end of the article

The following pictures show the interface of the circular and square screen watches when they are turned on for workout. When isPinned: 0 is set, you can see the floating battery and time bars at the top.

Under the circular screen of 480px, the height of the floating bar is 68px. Under the circular screen of 454 px, the height of the floating bar is scaled proportionally Math.ceil (454/480 * 68) = 64 px.

On a square screen with a height of 390px, the height of the floating bar is 60px.

Life Cycle​

Workout Extension is basically the same as Zepp OS Mini Program Lifecycle, with the addition of onResume and onPause lifecycles.

Before introducing the lifecycle, let's introduce a concept called "Pause" state. In this state, the context information of the application will be retained, but it cannot respond to the registered callback function, and the registered timer will pause.

After adding the "Workout Extension" plugin, trigger the onCreate lifecycle of app.js.

Then execute the onInit and build lifecycles of the "Workout Extension". Afterwards,app.js enters the "Pause" state until it enters the corresponding "Workout Extension".

"Workout Extension" has the feature of gaining focus, that is, when the page focuses on the "Workout Extension" plug-in, it will trigger the onResume life cycle, and when the "Workout Extension" loses focus, it will trigger the onPause life cycle.

info

When the "Workout Extension" plugin loses focus, it will enter the "Pause" state.

API restrictions​

"Workout Extension" has some limitations in UI interaction.

  • The drawing area is limited, and UI widgets can only be drawn within the boundaries of the device screen. For example, the drawing area size of "Workout Extension" on Amazfit T-Rex Ultra devices is consistent with the screen resolution of 454 x 454 px.
  • Can only display single-page content, does not support long page scrolling.
  • Sliding operation is not supported. Widgets such as SCROLL_LIST, VIEW_CONTAINER, PAGE_INDICATOR, SCROLL_BAR that support sliding or stacking layout are not supported on the page.
  • Does not support gesture monitoring.
  • Does not support button response.
  • Support CLICK event. Widgets within the page support click events.

Workout Extension i18n configuration​

"i18n": {
  "ar-EG": {
    "data-widget": {
      "widgets": [
        {
          "name": "Running Pace Master"
        }
      ]
    }
  },
  "ca-ES": {
    "data-widget": {
      "widgets": [
        {
          "name": "Running Pace Master"
        }
      ]
    }
  },
}

Full Example​

Please see the Zepp Health Github sample repository workout-extension

Three examples are provided in total

  • Running Data Assistant（Left side of the above picture）
  • Running Pace Master（Right side of the above picture）
  • Running Pace Master With Side Service（Demonstrated the use of Side App）

Appendix​

SubType workout type value​

subType valueMotion type
1Outdoor Running
2Treadmill (original indoor running)
3Walking
4Outdoor Cycling
5Free Training
6Pool Swimming
7Open Water Swimming
8Indoor Riding
9Elliptical Machine
10Mountaineering
11Cross Country Running
12Skiing
15Outdoor Hiking
17Tennis
18Football
19Ironman Triathlon
20Compound Motion
21Jump Rope
23Rowing Machine
24Indoor Fitness
40Indoor Walking
41Curling
42Snowboarding
43Alpine Skiing
44Outdoor Skating
45Indoor Skating
46Cross-Country Skiing
47Mountain Cycling
48BMX
49High Intensity Interval Training
50Core Training
51Mixed Aerobic
52Strength Training
53Stretching
54Climber
55Flexibility Training
57Step Training
58Stepper
59Gymnastics
60Yoga
61Pilates
62Surfing
63Hunting
64Fishing
65Sailing
66Outdoor Boating
67Skateboard
68Paddleboarding
69Roller Skating
70Rock Climbing
71Ballet
72Belly Dance
73Square Dance
74Street Dance
75Ballroom Dance
76Dance
77Zumba
78Cricket
79Baseball
80Bowling
81Squash
82Rugby
83Golf
84Golf swing
85Basketball
86Softball
87Gateball
88Volleyball
89Ping Pong
90Hockey
91Handball
92Badminton
93Archery
94Equestrian Sports
95Swordsmanship
96Karate
97Boxing
98Judo
99Wrestling
100Tai Chi
101Muay Thai
102Taekwondo
103Martial Arts
104Free Fighting
105Snowboarding
106Kitesurfing
108Climb the stairs
109Fitness
110Orienteering
111Group Exercise
112Latin Dance
113Jazz Dance
114Combat Exercise
115Hula hoop
116Frisbee
117Dart
118Flying a Kite
119Tug-of-war
120Kicking shuttlecock
121Beach Football
122Beach Volleyball
123Drifting
124Motorboat
125Bicycle
126Sled
127Orienteering
128Winter Biathlon
129Parkour
130Cross-training
131Race Walking
132Driving
133Paragliding
134One minute sit-ups
135One minute skipping rope
136Snowmobile
137Off-Road Motorcycle
138Dragon Boat
139Water Ski
140Kayaking
141Rowing
142Polo
143Spinning Bike
144Walking Machine
145Racquetball
146Folk Dance
147Jiu-Jitsu
148Fencing
149Horizontal Bar
150Parallel bars
151Billiards
152Sepak takraw
153Dodgeball
154Water Polo
155Fin swimming
156Synchronized Swimming
157Snorkeling
158Ice Hockey
159Swing
160Shuffleboard
161Table Football
162Shuttlecock
163Somatosensory Games
164Indoor Football
165Hip Hop Dance
166Pole Dance
167Battle Rope
168Break Dance
169Sandbag Ball
170Bocce
171Pull back the ball
172Indoor Surfing
173Chess
174Checkers
175Go
176Bridge
177Board Game
178Snowshoe Hiking
179Shooting
180Skydiving
181Downhill
182Bungee Jumping
183Trampoline
184Bouldering
185Modern Dance
186Disco
187Tap Dance
188Floor ball
189Electronic Sports
190ATV
191Football (without GPS)
192Playground Running
193Fishing (Number of Fishes)
194Indoor Rock Climbing
195Mountaineering and Skiing
196Outdoor Freediving
197Indoor freediving
198Fishing and Hunting
199Simple Tennis
200Wakewave Surfing
201Surfing (identify number of trips)
202Kitesurfing (Identification Gliding)
203Ultra Marathon