> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/mobile-sdks/planned-workouts-apple-watch.md).

# Planned workouts on Apple Watch

Put the plans you create with the Planned Workouts API on an Apple Health user's Apple Watch through the iOS or React Native SDK.

Plans you create with the [Planned Workouts API](https://docs.tryterra.co/planned-workouts-api/overview.md) for an Apple Health user appear on that person's Apple Watch, in the Workout app, on the day they are planned for.

* `schedulingStatus`: returns whether the SDK can put plans on this person's Watch. It never shows a prompt.
* `requestScheduling`: shows WorkoutKit's permission sheet, once, so the SDK can put plans on the Watch.
* `planned`: returns the person's planned workouts.
* `markComplete`: reports a planned workout as done.

Planned workouts must first be created using [Terra's REST API](https://docs.tryterra.co/planned-workouts-api/overview.md) on your backend. Once the person allows scheduling, every SDK sync run reads what changed and updates the Watch. There is no sync call to make.

## Before you begin

* The [iOS SDK](https://docs.tryterra.co/mobile-sdks/ios-sdk-2.md) or the [React Native SDK](https://docs.tryterra.co/mobile-sdks/react-native-sdk-2.md), connected with `connect(.health, ...)` (Swift) or `connect('health', ...)` (React Native).
* iOS 17 or later on the iPhone, and an Apple Watch paired with it. On anything else, `schedulingStatus()` returns `unsupported` and nothing is put on a Watch.
* No extra entitlement or background mode. Scheduling runs inside the SDK's existing sync runs.
* iOS only. On Android, `terra.plannedWorkouts` is `undefined`.

## Ask for scheduling permission

Putting plans on the Watch needs one permission, which WorkoutKit asks for with its own system sheet. Ask from a screen where it makes sense to the person, such as your training plan screen. The SDK never shows the sheet on its own.

{% tabs %}
{% tab title="Swift" %}
{% code title="TrainingPlanView\.swift" lineNumbers="true" %}

```swift
import TerraSDK

func enablePlannedWorkouts(connection: Connection) async {
    let plans = connection.workouts

    if await plans.schedulingStatus() == .notDetermined {
        await plans.requestScheduling()
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="React Native" %}
{% code title="TrainingPlanScreen.tsx" lineNumbers="true" %}

```typescript
import { terra } from './terra';

const enablePlannedWorkouts = async () => {
  const plans = terra.plannedWorkouts; // undefined on Android

  if (plans && (await plans.schedulingStatus()) === 'notDetermined') {
    await plans.requestScheduling();
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

`schedulingStatus()` returns one of:

| Status          | Meaning                                                                |
| --------------- | ---------------------------------------------------------------------- |
| `unsupported`   | Below iOS 17, or the device cannot schedule workouts. Hide the feature |
| `notDetermined` | Not asked yet. Call `requestScheduling()`                              |
| `denied`        | The person refused. Only the Settings app changes this                 |
| `authorized`    | Plans go on the Watch on every sync run                                |

When the person allows it, the SDK puts their plans on the Watch straight away.

## Create plans on your backend

Create and change plans with the [Planned Workouts API](https://docs.tryterra.co/planned-workouts-api/overview.md), for the Terra user the SDK connected. You don't call anything else in the app.

| In Terra          | On the Watch                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| A plan is created | Scheduled at 09:00 local time on its day. A plan for today created after 09:00 is scheduled a few minutes from now |
| A plan is changed | The workout is replaced, or moved to its new day                                                                   |
| A plan is deleted | The workout is removed                                                                                             |

Workouts your app schedules itself with WorkoutKit are left alone, and reported to Terra so your backend can see them.

### When the Watch is updated

Scheduling runs at the end of each sync run, so plans reach the Watch when the SDK next runs:

* **Scheduling allowed**: straight after `requestScheduling()` is allowed.
* **Permission grant or new link**: after a `permissions.request` that first asks for a category with an upload route, or a `connect` that makes a new link.
* **Foreground**: when the app becomes active, at most once every 15 minutes.
* **Background**: on the SDK's background refresh task.

A HealthKit background delivery wake uploads the new health data only. It does not update the Watch.

### Plans that cannot be scheduled

{% hint style="warning" %}
A plan WorkoutKit cannot represent is refused, and Terra is told why:

| Reason                 | Cause                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `activity_unsupported` | WorkoutKit cannot build a custom workout for this activity                                   |
| `goal_unsupported`     | A step's goal is one WorkoutKit refuses for this activity and location                       |
| `malformed`            | The workout has a goal, unit or step the SDK does not recognise, or no interval block to run |
| `no_workout`           | The plan has no workout to schedule                                                          |
| `past`                 | The plan's day has already passed on the device                                              |
| `completed`            | The plan is already done                                                                     |

Any copy of a refused plan already on the Watch is removed. When the Watch's schedule is full, the remaining plans stay queued and are scheduled as earlier sessions pass.
{% endhint %}

## Check what happened

Each run reports on [`diagnostics.events()`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#diagnostics.events):

* `plannedWorkoutsScheduled`, with how many plans were scheduled, removed and refused.
* `plannedWorkoutScheduleFailed`, with a failure code, when the run could not read the queue or reach WorkoutKit.

## Read plans in the app

You can also read the person's plans and report progress from the app:

{% tabs %}
{% tab title="Swift" %}
{% code lineNumbers="true" %}

```swift
let upcoming = try await plans.planned()
try await plans.markComplete(id: upcoming[0].id)
```

{% endcode %}
{% endtab %}

{% tab title="React Native" %}
{% code lineNumbers="true" %}

```typescript
const upcoming = await plans.planned();
await plans.markComplete(upcoming[0].id);
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**The mobile SDKs are only for Apple Health, Health Connect and Samsung Health.** These have no web API, so your app reads them on the phone and sends the data to Terra. Every other provider connects through the [Unified API](https://docs.tryterra.co/unified-api/getting-started) with no SDK.
{% endhint %}

## Next steps

* [Android SDK](https://docs.tryterra.co/mobile-sdks/android-sdk-2.md): connect Health Connect and Samsung Health.
* [React Native SDK](https://docs.tryterra.co/mobile-sdks/react-native-sdk-2.md): use planned workouts from React Native.
