Skip to main content
Samsung Developer Program

Develop Watch Face Apps

 

Note: In August 2018, Samsung Gear became Samsung Galaxy Watch. Information referring to Galaxy Watch also applies to earlier Gear devices and apps, unless stated otherwise. 

Develop Watch Face Apps
Watch face apps are displayed on the home screen of the watch. Although the clock is the watch face app's main functionality, you can display other information such as sensor data (e.g., heart rate, accelerometer). You can customize a watch face application by designing your own style and providing other information, such as news headlines and weather information.

This section describes how to create a simple watch face using the Galaxy Watch Designer (formerly Gear Watch Designer) tool and an API-based watch face app on the Tizen platform using Tizen Studio. You can include in-app purchase (IAP) items on your Galaxy watch face. 

Galaxy Watch Designer

The Galaxy Watch Designer tool is a one-stop shop for designers who want to develop and distribute their own watch faces. This tool is available for Windows and Mac users only.

To learn more about and download the Galaxy Watch Designer tool, click here.

To develop watch faces using Galaxy Watch Designer, start here.

Tizen web and native app development

See create a sample watch face using web API for information about how to develop a watch face app on the Tizen platform.

The Tizen platform supports two primary application types:

  • Web apps are Internet-enabled apps that are accessible through the mobile device’s web browser. A web framework provides state-of-the-art HTML5/W3C APIs, web UI framework, supplementary APIs, and additional Tizen device APIs. Web has strong portability, ease of app development, and has a minimal learning curve.
  • A native framework supports full-featured native application development and provides a variety of features such as background service and image and face recognition. Native apps use the native API, which provides all of the memory management and performance benefits that come with building applications for Linux in C.

For more detailed information about web and native APIs, see the following links:

Web and native applications Differences between Tizen web-specific and native-specific applications, Tizen architecture, and Tizen documentation https://developer.tizen.org/development/getting-started/overview
Web app introduction Guides you to familiarity with Tizen web API programming and application models https://developer.tizen.org/development/getting-started/web-application
Web app development Helps you create and develop your first web app http://developer.samsung.com/gear/develop/creating-your-first-app/web
Native app introduction Guides you to familiarity with Tizen native API programming and application models https://developer.tizen.org/development/getting-started/native-application
Native app development Helps you create and develop your first native app http://developer.samsung.com/gear/develop/creating-your-first-app/native

Standalone and companion apps  

A watch app that was developed using either a web or native application can be either a standalone or a companion app.

Standalone

A standalone watch app can function on its own and does not require any other app to execute its functionality.

  • Standalone watch apps may or may not need network connectivity (the calculator app is an example of an app that does not need network connectivity in order to function).
  • Standalone apps can also handle authentication on the watch application.

Companion

Companion apps consist of two apps working together. One app runs on the watch, and the other is an Android app running on the Android device.

  • Most companion apps use the phone's connectivity to communicate to the cloud. If the watch is no longer connected to the phone, it can use its own Wi-Fi connectivity (or 3G) to talk to the cloud. 
  • Watch companion apps can take advantage of Android companion apps to get user credentials. 
  • Samsung provides a Samsung Accessory Protocol (SAP) library (Samsung Accessory SDK), which can be downloaded separately. SAP library has all the APIs necessary to handle the communication between watches and Android apps.
  • To enable host devices (such as the phone) to recognize companion apps, specific metadata must be declared on both the host Android app's manifest file and on the watch app’s config.xml or Tizen manifest file. For more information, see: http://developer.samsung.com/gear/develop/creating-your-first-app/web-companion/configuration

In-app items

Within watch apps (companion or standalone, web or native), you can sell commercial in-app items (such as virtual items, increasing levels of play, advanced app features) by integrating In-App Purchase (IAP) functionality.

Gear_InAppItem_Purchase_UI.png

For more information, see the Galaxy Watch In-App Purchase Items section.

Additional information

Screen capture

You can capture and review any watch screenshot. After transferring them to a connected compatible Android smartphone (including any Samsung smartphone), you can download screenshot files and use them for your app development and marketing purposes. 

To capture, review, download, and delete screenshots:

Gear_Screen_Capture.png

To capture a screenshot:

Navigate to the screen to be captured.

  1. Press and hold the Power (lower) button. 
  2. Swipe the display from left to right.
Gear_Review_Captured_Screenshots.png

To review captured screenshots:

Screenshots are saved in the Gallery app. 

 

Gear_1_Screenshot_Download.png

 

 

Gear_1_Screenshot_Delete.png

To download or delete one captured screenshot:

  1. In the Gallery, navigate to and tap a captured screenshot to select it.
  2. To send the screenshots to phone:
    1. Tap the More Options icon.
    2. Tap Send to phone.
  3. To delete the selected screenshot:
    1. In the Gallery, tap the More Options icon.
    2. Tap Delete.
    3. To delete multiple images, long-press and select the images you want to delete, and click the x.

Gear_Select_Multiple_SS.png

Gear_Download_Multiple_SS.png

Gear_Delete_Multiple_SS.png

To download or delete many captured screenshots:

  1. Select the screenshots:
    1. In the Gallery, navigate to and tap a captured screenshot.
    2. Press and hold the screen.
    3. In the Captured Screenshot Gallery:
      1. Swipe left or right to navigate to each captured screenshot.
      2. Tap an image to select it (surrounded by a blue circle); tap again to unselect it.
        Note: The number of currently selected screenshots is displayed.
         
  2. To download and use selected screenshots:
    1. Tap the More Options icon.
    2. Tap Send to phone.
    3. If necessary, connect to the phone:
      1. Position the phone near the watch.
      2. In the Connect via Bluetooth screen, tap the Checkmark icon.
    4. Transfer screenshot from the Android phone to a computer:
      1. Connect the Android phone to a computer.
      2. In the computer file manager:
        1. Transfer the screenshot from the phone to the computer storage.
        2. Use the captured screenshot.
           
  3. To delete the selected images:
    1. Tap Delete.
    2. In the Delete [#] photos? screen, tap the Checkmark icon.

Create a sample watch face app using web API

The Tizen SDK provides everything you need to develop apps for Tizen, including the IDE and the SDK tools.

This section provides information to create a sample watch face app using Tizen Studio. The fully functional watch face sample application described in this section is located in GitHub: 
https://github.com/Samsung-US-Developer-Support/WatchFace

Prerequisites

Set up a PC with Tizen SDK with a Wearable profile.

Create a new project

  1. Click File > New > Tizen Project.

    CreateNewTizenProject.PNG

  2. In the New Tizen Project wizard, select Template, and click Next.

    TizenProjectTemplate.PNG

  3. Select profile Wearable and version Wearable v2.3.1, and click Next.

    TizenProfileWearable.PNG

  4. Select Web Application as the application type, and click Next.
  5. Select Basic UI as the application template, and click Next.

    TizenBasicUITemplate.PNG

  6. Enter a project name in the Define the project properties screen, and click Finish.

    TizenProjectPropertiesName.PNG

Modify the config.xml file

Add category

  1. From Project Explorer, open the config.xml file.
  2. Click the Tizen tab, and scroll down to Category.
  3. Click the + icon, and select http://tizen.org/category/wearable_clock.

    AddCategory.PNG

  4. Save the config.xml file.

Add privileges

  1. From Project Explorer, open config.xml.
  2. Click the Privileges tab.
  3. Click the + icon, and add http://tizen.org/privilege/application.launch and http://tizen.org/privilege/healthinfo privileges.
  4. Save the config.xml file.

AddPrivileges.PNG

Add ambient support

To support ambient mode in the watch face, add ambient_support="enable" in the config.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns:tizen="http://tizen.org/ns/widgets" xmlns="http://www.w3.org/ns/widgets"
                         id="http://yourdomain/ArtBoardWatch" version="1.0.0" viewmodes="maximized">
                                    <tizen:application id="OqHNdZ1Wb7.ArtBoardWatch" package="OqHNdZ1Wb7" required_version="2.3.2"
                         ambient_support="enable"/>
</widget>

To use ambient mode, you must enable it in the device Settings, as follows:

Setting > Display > Watch always on

Ambient mode activates only when you are wearing the watch on your wrist. See the following link for more details:

https://developer.tizen.org/development/training/web-application/getting-started/creating-your-first-tizen-wearable-web-watch-application

Add HTML code to the index.html file

  1. From Project Explorer, open index.html and change the body element, as shown below:
  • background: Div element shows the watch background image background.png.
  • index: Div element shows the watch index using the index.png image as div background.
  • components-steps: Container div with three child divs - step-icon, step-count, and step-text - for step-count GUI.
  • components-main: Container div with three child divs - one each for the hour, minute, and second hand images.
  • action-steps: Transparent div. Tap it to launch the S Health app.
  1. Save and close index.html.
<body>
    <div id="container">
        <div id="background">
          <div id="index"></div>

          <div id="components-steps">
              <div id="step-icon"></div>
              <div id="step-count">0</div>
              <div id="step-text">Steps</div>
            </div>

            <div id="components-main">
                <div id="hand-main-hour"></div>
                <div id="hand-main-minute"></div>
                <div id="hand-main-second"></div>
            </div>
         <div id="action-steps"></div>

        </div>
    </div>
</body>

Add image resources to the project

  1. Create a new folder in the root folder of your project, and name it image.
  2. We are using our own image resources for watch hands, background, and the step-count icon. Copy the following images to your project’s image folder:
  • background.png – Watch background
  • index.png – Watch index
  • hour_hand.png – Hour watch hand
  • minute_hand.png – Minute watch hand
  • seconds_hand.png –  Seconds watch hand
  • steps_bg_03.png – Background image for step count GUI
  • icon_steps_03.png –  Step icon

            ImageResources.PNG

Add JavaScript code 

  1. From Project Explorer, open js > main.js.
  2. Add application logic, as shown below.

This function rotates the hour, minute and second hands. The Java script "style.transform" property is used to rotate the "element."

function rotateElement(elementID, angle) {
        var element = document.querySelector("#" + elementID);

        element.style.transform = "rotate(" + angle + "deg)";

}

This function updates the hour, minute, and second hands according to the current time. This function is called every second. This function also is called when the time zone or visibility of the watch face is changed.

function updateTime() {
       var datetime = tizen.time.getCurrentDateTime(),
       hour = datetime.getHours(),
       minute = datetime.getMinutes(),
       second = datetime.getSeconds();

       // Rotate the hour/minute/second hands
       rotateElement("hand-main-hour", (hour + (minute / 60) + (second / 3600)) * 30);
       rotateElement("hand-main-minute", (minute + second / 60) * 6);
       rotateElement("hand-main-second", second * 6);
}

This is a callback function, which is invoked on pedometer data changes. It then updates step count in the watch face accordingly.

function onchangedCB(pedometerInfo)
{
      var element = document.querySelector("#step-count");
      element.innerHTML = pedometerInfo.accumulativeTotalStepCount;
}

This launches the S-Health application, which is triggered when the user tap on steps count.

        function onOpenShealth() {
             console.log("launching SHealth");

                // Launch sHealth application explicitly
                tizen.application.launch("com.samsung.shealth",
                          function() {console.log("launch application control succeed"); },
                                 function(e) {console.log("launch application control failed. reason: "
+ e.message); }
                        );
       }

Sets default event listeners. This function binds click events to step count and to ambient mode (Always-on mode). When user tap on step count, it triggers the "onOpenSHealth" callback.

        function bindEvents() {
                // Add an event listener to update the screen immediately when the device wakes up
                document.addEventListener("visibilitychange", function() {

                if (!document.hidden) {
                            updateTime();

                            if (isAmbientMode === true) {
                                // Rendering ambient mode case
                                activateMode("Ambient");
                            } else {
                                // Rendering normal case
                                activateMode("Normal");
                            }
                     }
               });

               // Add an eventListener for ambientmodechanged, this event will get trigger only when user wear the watch on his/her wrist.
               window.addEventListener("ambientmodechanged", function(e) {
                       if (e.detail.ambientMode === true) {
                            // Rendering ambient mode case
                            activateMode("Ambient");
                       } else {
                           // Rendering normal case
                           activateMode("Normal");
                       }
               });

              // Add an click event listener of div to launch sHealth application
              document.getElementById("action-steps").addEventListener("click", onOpenShealth);

              // Add eventListener to update the screen when the time zone is changed\
              tizen.time.setTimezoneChangeListener(function() {
                    updateTime();
             });

             //Add listner for pedometer data change
             tizen.humanactivitymonitor.setAccumulativePedometerListener(onchangedCB);\
} 

This function activates normal watch face on the Gear device. It first removes the CSS class that is used for ambient mode, and adds the CSS used for a normal watch face. It changes the visibility of the components that were "hidden" in ambient mode to "visible."

    function showNormalWatch(){

             var myButtonClasses = document.getElementById("background").classList;

             if (myButtonClasses.contains("ambientBackground")) {
             myButtonClasses.remove("ambientBackground");
             }
             
             myButtonClasses.add(“normalBackground”);

             document.getElementById(("hand.main.second").style.visibility     = “visible”;
             document.getElementById(("components-steps").style.visibility     = “visible”;
             document.getElementById(("action-steps").style.visibility         = “visible”;
     }    

This function activates ambient watch face.

    function showAmbientWatch(){I

    var myButtonClasses = document.getElementById("background").classList;

    if (myButtonClasses.contains("normalBackground")){
    (myButtonClasses.remove("normalBackground");
    }

    myButtonClasses.add("ambientBackground");

    document.getElementById("hand-main-second").style.visibility   = "hidden";
    document.getElementById("components-steps").style.visibility   = "hidden";
    document.getElementById("action-steps").style.visibility       = "hidden";
} 
Initiates the watch face application.

     function init() {
              bindEvents();

              // Update the watch hands every second
              setInterval(function() {
                    updateTime();
              }, 1000);
      }

      window.onload = init();

}());

Add styles to HTML elements 

  1. From Project Explorer, open css > style.css.
  2. Add the following code to the file:

html, body {
       width: 100%;
       height: 100%;
       margin: 0px;
       overflow: hidden;
}


Specify the style property for the Div id “container” declared in index.html.

#container {
       width: 100%;
       height: 100%;
       overflow: hidden;
}


Define a class to set the properties of watch face “background” when it is in “normal” mode.

.normalBackground {
      width: 100%;
      height: 100%;
      background-image: url("../image/background.png");
}


Define a class to set the properties of watch face “background” when it is in “ambient” mode. Here we are changing the image resource by specifying the URL of where the image is stored.

.ambientBackground {
      width: 100%;
      height: 100%;
      background-image: url("../image/ambient.png");
}


Specify the style property for the Div id “index” declared in index.html. We are loading the image resource that shows the index of the watch.

#index {
      position: absolute;
      width: 100%;
      height: 100%;
      background-image: url("../image/index.png");
}


Specify the style property for the Div id “components-main” declared in index.html.

#components-main {
        position: absolute;
        width: 100%;
}


Specify the style property for the Div id “hand-main-hour” declared in index.html. We are also loading the hour-hand image.

#hand-main-hour {
        position: absolute;
        left: 170px;
        top:80px;
        width: 21px;
        height: 111px;
        background-image: url("../image/hour_hand.png");
        transform-origin: 50% 90%;

}


Specify the style property for the Div id “hand-main-minute” declared in index.html, and load the minute-hand image.

#hand-main-minute {
        position: absolute;
        left: 174px;
        top: 38px;
        width: 12px;
        height: 149px;
        background-image: url("../image/minute_hand.png");
        background-position: center top;
        background-size: contain;
        transform-origin: 50% 95.3%;
}


Specify the style property for the Div id “hand-main-second” declared in index.html, and load the second-hand image.

#hand-main-second {
        position: absolute;
        left: 174px;
        top: 32px;
        width: 12px;
        height: 178px;
        background-image: url("../image/seconds_hand.png");
        background-position: center top;
        background-size: contain;
        transform-origin: 50% 83.15%;
}


Specify the style property for the Div id “components-steps” declared in index.html, and load the step-count image.

#components-steps {
        position: absolute;
        left: 134px;
        top: 213px;
        width: 92px;
        height: 92px;
        background-image: url("../image/steps_bg_03.png");
        background-size: contain;
}


Specify the style property for the Div id “step-icon” declared in index.html, loading the background of the step-count icon.

#step-icon {
      position: absolute;
      left: 0px;
      top: 0px;
      width: 92px;
      height: 92px;
      background-image: url("../image/icon_steps_03.png");
      background-size: contain;
}


Specify the style property for the Div id “step-count” declared in index.html.

#step-count {
      position: absolute;
      left: 0px;
      top: 38px;
      width:92px;
      height:20px;
      color:#116DD1;
      text-align: center;
      font-size: 20px;
      font-weight: bold;
}


Specify the style property for the Div id “step-text” declared in index.html.

#step-text {
      position: absolute;
      left: 0px;
      top: 58px;
      width:92px;
      height:20px;
      color:#AAAAAA;
      text-align: center;
}


Specify the style property for the Div id “action-steps” declared in index.html. We are using a CSS property called “-webkit-tap-highlight-color” to give a visual cue to users. It changes color after the user taps on it.

#action-steps {
       position: absolute;
       left: 134px;
       top: 213px;
       width: 92px;
       height: 92px;
       -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
}

Replace the default icon 

Replace the icon.png file in your project with the WatchSample icon.png file.

  1. From Project Explorer, go to the folder containing the icon.png file.
  2. Replace the icon.png file with your own icon for your project.

Run the watch face application

From Project Explorer, right-click on your project, and select Run As > 1 Tizen Web Application.

RunWatchFaceApplication.PNG

The watch face looks like this:

TizenWatchFace.PNG

Other resources

The following table provides links to other documentation: 

Introduction      
  UI components   Link to details about Gear wearable app UI components. https://developer.tizen.org/design/wearable/ui-components
  Getting the Certificates   Creating, importing, and using Samsung certificates. http://developer.samsung.com/gear/develop/getting-certificates
UI Practices       
  Tizen Advanced UI   TAU library and W3C and HTML5 principles to create the proper visual interface for your web app https://developer.tizen.org/development/guides/web-application/user-interface
  User interface   EFL library principles to create the proper visual interface for your native app https://developer.tizen.org/development/guides/native-application/user-interface
API Guides      
  Tizen web guides   Guidelines for using Tizen, W3C, HTML5, and supplementary features in your web app https://developer.tizen.org/development/guides/web-application
  Tizen native API guides   Guidelines for using native Tizen features in your native app https://developer.tizen.org/development/guides/native-application
Tutorials       
  Introduction to web applications   Instructions to use Tizen, W3C, HTML5, and supplementary features in your web app https://developer.tizen.org/development/training/web-application
  Introduction to native applications   Instructions to use Tizen features in your native app https://developer.tizen.org/development/training/native-application
API References      
  Tizen APIs (web apps)   Purposes of Tizen and W3C, HTML5, supplementary web API modules, and their submodules for web apps, and links to module guides, tutorials, and API references https://developer.tizen.org/development/getting-started/web-application/understanding-tizen-programming/tizen-apis
  Tizen APIs (native apps)   Purposes of native Tizen API modules and their submodules for native apps, and links to module guides, tutorials, and API references https://developer.tizen.org/development/getting-started/native-application/understanding-tizen-programming/tizen-apis
Sample Code      
  Web application samples   How to get web app example code through the Tizen IDE and links to sample code https://developer.tizen.org/development/sample/web
  Native application samples   How to get native app example code through the Tizen IDE and links to sample code https://developer.tizen.org/development/sample/native