Skip to content

Commit

Permalink
Improve documentation of datalayer phone-ui (#2083)
Browse files Browse the repository at this point in the history
  • Loading branch information
@luizgrp
luizgrp authored Feb 29, 2024
1 parent 565a1e6 commit 7afb4f9
Show file tree
Hide file tree
Showing 3 changed files with 198 additions and 81 deletions.
145 changes: 80 additions & 65 deletions docs/datalayer-helpers-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,27 @@ phone.

## Getting started

1. Include the necessary dependency:
1. Include the necessary dependency:

```
dependencies {
implementation "com.google.android.horologist:horologist-datalayer-watch:<version>"
}
```
```
dependencies {
implementation "com.google.android.horologist:horologist-datalayer-watch:<version>"
}
```

and
and

```
dependencies {
implementation "com.google.android.horologist:horologist-datalayer-phone:<version>"
}
```
```
dependencies {
implementation "com.google.android.horologist:horologist-datalayer-phone:<version>"
}
```

For your watch and phone projects respectively.
For your watch and phone projects respectively.

2. Add the capabilities

Add a `wear.xml` file in the `res/values` folder with the following content:
Add a `wear.xml` file in the `res/values` folder with the following content:

```
<resources xmlns:tools="http://schemas.android.com/tools"
Expand All @@ -41,8 +41,8 @@ phone.
</string-array>
</resources>
```
and
and
```xml
<resources xmlns:tools="http://schemas.android.com/tools"
Expand All @@ -56,10 +56,10 @@ phone.
</resources>
```
on your wear and phone projects respectively.
on your wear and phone projects respectively.
For more details, see
[Specify capability names for detecting your apps](https://developer.android.com/training/wearables/apps/standalone-apps#capability-names).
For more details, see
[Specify capability names for detecting your apps](https://developer.android.com/training/wearables/apps/standalone-apps#capability-names).
3. Initialize the client including passing a `WearDataLayerRegistry`.
Expand All @@ -70,50 +70,64 @@ phone.
// on your phone project
val appHelper = PhoneDataLayerAppHelper(context, wearDataLayerRegistry)
```
## Check API availability
This API relies on Google Play services to be available and up-to-date on the device. You can check
the availability with:
```kotlin
if (!phoneDataLayerAppHelper.isAvailable()) {
// display error
}
```

Please refer
to [GoogleApiAvailability](https://developers.google.com/android/reference/com/google/android/gms/common/GoogleApiAvailability#makeGooglePlayServicesAvailable(android.app.Activity))
if you would like to display an UI to request the user to install or update Google Play.

## Connection and installation status

The `DataLayerAppHelper.connectedNodes()` returns information about connected devices. You could
invoke this method at startup or while the app is running.

```kotlin
val connectedNodes = appHelper.connectedNodes()
val connectedNodes = appHelper.connectedNodes()
```

The resulting list might will contain entries such as:

```
AppHelperNodeStatus(
id=7cd1c38a,
displayName=Google Pixel Watch,
appInstallationStatus=Installed(nodeType=WATCH),
surfacesInfo=# SurfacesInfo@125fcbff
complications {
instance_id: 1234
name: "MyComplication"
timestamp {
nanos: 738000000
seconds: 1680015523
}
type: "SHORT_TEXT"
}
tiles {
name: "MyTile"
timestamp {
nanos: 364000000
seconds: 1680016845
}
}
usage_info {
timestamp {
nanos: 669000000
seconds: 1701708501
}
usage_status: USAGE_STATUS_LAUNCHED_ONCE
usage_status_value: 1
}
)
AppHelperNodeStatus(
id=7cd1c38a,
displayName=Google Pixel Watch,
appInstallationStatus=Installed(nodeType=WATCH),
surfacesInfo=# SurfacesInfo@125fcbff
complications {
instance_id: 1234
name: "MyComplication"
timestamp {
nanos: 738000000
seconds: 1680015523
}
type: "SHORT_TEXT"
}
tiles {
name: "MyTile"
timestamp {
nanos: 364000000
seconds: 1680016845
}
}
usage_info {
timestamp {
nanos: 669000000
seconds: 1701708501
}
usage_status: USAGE_STATUS_LAUNCHED_ONCE
usage_status_value: 1
}
)
```

## Responding to availability change
Expand All @@ -124,10 +138,10 @@ on the phone when the watch is connected.

```kotlin
val nodes by appHelper.connectedAndInstalledNodes
.collectAsStateWithLifecycle()
.collectAsStateWithLifecycle()
```

## Installing the app on the other device
## Installing the app on the other device

Where the app isn't installed on the other device - be that phone or watch - then the library offers
a one step option to launch installation:
Expand All @@ -136,27 +150,27 @@ a one step option to launch installation:
appHelper.installOnNode(node.id)
```

## Launching the app on the other device
## Launching the app on the other device

If the app is installed on the other device, you can launch it remotely:

```kotlin
val result = appHelper.startRemoteOwnApp(node.id)
```

## Launching a specific activity on the other device
## Launching a specific activity on the other device

In addition to launching your own app, you may wish to launch a different
activity as part of the user journey:

```kotlin
val config = activityConfig {
val config = activityConfig {
classFullName = "com.example.myapp.MyActivity"
}
appHelper.startRemoteActivity(node.id, config)
```

## Launching the companion app
## Launching the companion app

In some cases, it can be useful to launch the companion app, either from the watch or the phone.

Expand All @@ -165,13 +179,13 @@ user the option to navigate to the companion app to install it:

```kotlin
if (node.surfacesInfo.tilesList.isEmpty() && askUserAttempts < MAX_ATTEMPTS) {
// Show guidance to the user and then launch companion
// to allow the to install the Tile.
val result = appHelper.startCompanion(node.id)
// Show guidance to the user and then launch companion
// to allow the to install the Tile.
val result = appHelper.startCompanion(node.id)
}
```

## Tracking Tile installation (Wear-only)
## Tracking Tile installation (Wear-only)

To determine whether your Tile(s) are installed, add the following to your `TileService`:

Expand All @@ -189,7 +203,8 @@ wearAppHelper.markTileAsRemoved("SummaryTile")

## Tracking Complication installation (Wear-only)

To determine whether your Complication(s) are in-use, add the following to your `ComplicationDataSourceService`:
To determine whether your Complication(s) are in-use, add the following to
your `ComplicationDataSourceService`:

In `onComplicationActivated`:

Expand All @@ -205,7 +220,7 @@ wearAppHelper.markComplicationAsDeactivated("GoalsComplication")

## Tracking the main activity has been launched at least once (Wear-only)

To mark that your main activity on the watch app has been launched once, use:
To mark that your main activity on the watch app has been launched once, use:

```kotlin
wearAppHelper.markActivityLaunchedOnce()
Expand All @@ -219,9 +234,9 @@ val connectedNodes = appHelper.connectedNodes()
node.surfacesInfo.usageInfo.usageStatus
```

## Tracking the app has been set up (Wear-only)
## Tracking the app has been set up (Wear-only)

To mark that the user has completed in the app the necessary setup steps such that it is ready
To mark that the user has completed in the app the necessary setup steps such that it is ready
for use, use the following:

```kotlin
Expand Down
Loading

0 comments on commit 7afb4f9

Please sign in to comment.