Lifecycle and analytics events

TileService is a bound service. Your TileService is bound as a result of your app request or if the system needs to communicate with it. A typical bound-service lifecycle contains the following four callback methods: onCreate(), onBind(), onUnbind(), and onDestroy(). The system invokes these methods each time the service enters a new lifecycle phase.

Important: Your TileService will still go through the typical Service lifecycle. However, TileService differs from most other bound services because it contains TileService-specific lifecycle methods that your app can react to. The Service lifecycle methods and the TileService lifecycle methods are called in two separate asynchronous threads.

In addition to the callbacks that control the bound-service lifecycle, you can implement other methods specific to the TileService lifecycle. All tile services must implement onTileRequest() and onTileResourcesRequest() to respond to requests for updates from the system.

• onTileAddEvent(): The system calls this method only when the user adds your tile for the first time, and if the user removes and adds your tile again. This is the best time to do any one-time initialization.

  onTileAddEvent() is only called when the set of tiles are reconfigured, not whenever a tile is created by the system. For example, when the device is rebooted or powered on, onTileAddEvent() is not called for the tiles that had already been added. You can use getActiveTilesAsync() instead to get a snapshot of which tiles belonging to you are active.

• onTileRemoveEvent(): The system calls this method only if the user removes your tile.

• onTileEnterEvent(): The system calls this method when a tile provided by this provider comes into view on screen.

• onTileLeaveEvent(): The system calls this method when a tile provided by this provider goes out of view on the screen.

• onTileRequest(): The system calls this method when the system requests a new timeline from this provider.

• onTileResourcesRequest(): The system calls this method when the system requests a resource bundle from this provider. This can happen on the first time a Tile is being loaded or whenever the resource version changes.

Note: Don't require (or rely on) phases to occur in any particular order. onTileAddEvent() may only be called when your tile is added by a user. onTileEnterEvent() and onTileLeaveEvent() may be called multiple times throughout the TileService lifecycle. onTileRemoveEvent() will never be called if the user does not remove the tile.

Query which tiles are active

Active tiles are tiles which have been added for display on the watch. Use TileService's static method getActiveTilesAsync() to query which tiles belonging to your app are active.

Caution: The result reflects the list of active tiles at the time the call was made, which might have changed by the time the result is received. Use onTileAddEvent() and onTileRemoveEvent() callbacks for scheduling actions that need to happen when your tile becomes either active or inactive.