Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve documentation of datalayer phone-ui #2083

Merged
merged 1 commit into from
Feb 29, 2024
Merged

Improve documentation of datalayer phone-ui #2083

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 80 additions & 65 deletions docs/datalayer-helpers-guide.md
View file
Open in desktop
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
Loading