> 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/ios-migrating-to-2.md).

# iOS upgrade guide

Move an iOS app from TerraiOS 1.x to 2.x: the package and import change, Info.plist and entitlements, reference IDs, and old calls mapped to new ones.

`TerraiOS` 2.x is a rebuild, not an update. The package URL stays the same, but the module, the entry point and every call changed. Plan it as a migration.

## Update the package and the import

2.x installs with Swift Package Manager. Change the version rule on `https://github.com/tryterra/TerraiOS` to `from: "2.0.0"` (any 2.x release), and link the `TerraSDK` product.

If you installed 1.x with CocoaPods, remove `pod 'TerraiOS'` from your `Podfile` and run `pod install`, then add the package in Xcode with Swift Package Manager. CocoaPods trunk becomes read-only on 2 December 2026, so releases after that are published only through Swift Package Manager.

Change every import:

{% code title="YourApp.swift" %}

```swift
// 1.x
import TerraiOS

// 2.x
import TerraSDK
```

{% endcode %}

## Update Info.plist and entitlements

|                                           | 1.x                                        | 2.x                       |
| ----------------------------------------- | ------------------------------------------ | ------------------------- |
| `BGTaskSchedulerPermittedIdentifiers`     | `co.tryterra.data.post.request`            | `co.tryterra.sdk.refresh` |
| Background modes                          | Background fetch and Background processing | Background fetch          |
| HealthKit background delivery entitlement | Required                                   | Required                  |
| `NSHealthUpdateUsageDescription`          | Required                                   | Required                  |

The minimum iOS version is now 15.

## Move `reference_id` to your backend

In 1.x the app passed `referenceId` to `Terra.instance`. In 2.x your backend sets it when it mints the token. Use the same value 1.x used, so existing users keep their `user_id`:

{% code title="Your backend" %}

```bash
curl --request POST \
  --url 'https://api.tryterra.co/v2/auth/generateAuthToken?reference_id=<YOUR_USER_ID>' \
  --header 'dev-id: <YOUR_DEV_ID>' \
  --header 'x-api-key: <YOUR_API_KEY>'
```

{% endcode %}

The app still names the person, on every `connect`: [`connect(.health, for: .reference(user.id))`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terra.connect), with the same value your backend puts in the token. The SDK restores a stored link only for the person it was made for. When someone else signs in on the same phone, it retires the old link and links again, so their data does not arrive under the previous person's `reference_id`. If your backend sends no `reference_id`, pass [`.anonymous`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#enduser). Terra still trusts only the reference inside the token.

## Map the calls

| 1.x                                                                          | 2.x                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Terra.instance(devId:referenceId:requestPermissions:completion:)`           | [`Terra(devID:tokenProvider:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terra.init). Synchronous, no completion handler. Build it once, at launch                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `initConnection(type: .APPLE_HEALTH, token:customReadTypes:schedulerOn:)`    | [`try await terra.connect(.health, for: .reference(user.id))`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terra.connect), then [`try await terra.permissions.request(read:write:workouts:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#permissions.request)                                                                                                                                                                                                                                                                                                                                                     |
| `token:` argument on `initConnection`                                        | The `tokenProvider` closure on `Terra(...)`, called only when a new link is needed. Or `connect(.health, for: .reference(user.id), using: token)` for a token already in hand                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `customReadTypes: Set<CustomPermissions>`                                    | [`read: [DataCategory]`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#datacategory), for example `[.daily, .sleep, .activity, .body]`. In 2.3.0 and later, to ask for single types as `CustomPermissions` did, use [`readTypes: [HealthDataType]`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#healthdatatype). [Permissions](https://docs.tryterra.co/reference/mobile-sdks/permissions-mapping#individual-types) lists the types                                                                                                                                                                                  |
| `requestHealthKitPermissions()`                                              | `terra.permissions.request(...)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `requestPermissions: false`                                                  | Not needed. `Terra(...)` and `connect` never present a sheet. Only `permissions.request` does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `referenceId:` argument on `Terra.instance`                                  | `reference_id` on your backend's token request, and the [`EndUser`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#enduser) you pass to every `connect`                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `getUserId(type: .APPLE_HEALTH)`                                             | [`try await terra.connections`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terra.connections), and [`connection.userID`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#connection) on what `connect` returns                                                                                                                                                                                                                                                                                                                                                                                                        |
| `Terra.setUpBackgroundDelivery()`                                            | [`BackgroundSync.register(terra: terra)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#backgroundsync.register). See [Set up background delivery](https://docs.tryterra.co/mobile-sdks/ios-sdk-2.md#set-up-background-delivery)                                                                                                                                                                                                                                                                                                                                                                                                  |
| `schedulerOn:`                                                               | Removed. Background delivery is `BackgroundSync.register`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `getDaily`, `getBody`, `getSleep`, `getActivity`, ... with `toWebhook: true` | Removed from the device. [Historical data requests](https://docs.tryterra.co/unified-api/requesting-historical-data.md) from your backend with `to_webhook=true`. The device serves it on its next run                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `getDaily` with `toWebhook: false`                                           | [`terra.daily.steps(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#dailymetrics.steps). In 2.2.0 and later, also [`terra.daily.totals(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#dailymetrics.totals) for each day's distance, active and basal energy, flights climbed and exercise minutes, [`terra.daily.intraday(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#dailymetrics.intraday) for the samples under those totals, and [`terra.body.restingHeartRate(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#bodymetrics.restingheartrate) for resting heart rate |
| `getBody` with `toWebhook: false`                                            | [`terra.body.heartRate(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#bodymetrics.heartrate). In 2.2.0 and later, also [`terra.body.restingHeartRate(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#bodymetrics.restingheartrate) and [`terra.body.readings(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#bodymetrics.readings) for weight, height, BMI, body fat, lean mass, HRV, VO2 max, blood pressure, blood glucose, oxygen saturation, temperature and respiratory rate                                                                                                           |
| `getSleep` with `toWebhook: false`                                           | [`terra.sleep.segments(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#sleepmetrics.segments)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `getActivity` with `toWebhook: false`                                        | [`terra.activity.workouts(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#activitymetrics.workouts). In 2.2.0 and later, each `Workout` also carries `title`, and [`terra.activity.routes(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#activitymetrics.routes) and [`terra.activity.intensity(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#activitymetrics.intensity) return GPS tracks and speed, power and cadence                                                                                                                                                                   |
| `getNutrition` with `toWebhook: false`                                       | 2.2.0 and later: [`terra.nutrition.quantities(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#nutritionmetrics.quantities), one value per nutrient sample, and [`terra.nutrition.hydration(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#nutritionmetrics.hydration) for water. Before 2.2.0 there is no local read: read nutrition from Terra's API or your webhook on your backend                                                                                                                                                                                                                       |
| `getMenstruation` with `toWebhook: false`                                    | 2.2.0 and later: [`terra.menstruation.flow(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#menstruationmetrics.flow) and [`terra.menstruation.events(in:)`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#menstruationmetrics.events). Request `.menstruation` first. Before 2.2.0 there is no local read: read it from Terra's API or your webhook                                                                                                                                                                                                                                                               |
| `getAthlete` with `toWebhook: false`                                         | 2.2.0 and later: [`terra.athlete.profile()`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#athletemetrics.profile). Request `.athlete` first. Before 2.2.0 there is no local read: read it from Terra's API or your webhook                                                                                                                                                                                                                                                                                                                                                                                                       |
| `subscribe(forDataTypes:)` with `Terra.updateHandler`                        | [`for await _ in await terra.daily.changes()`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#dailymetrics.changes), and the other namespaces' `changes()`. A hint that something changed, not the samples: read them with the local reads above                                                                                                                                                                                                                                                                                                                                                                                   |
| `Terra.checkAuthentication(connection:devId:)`                               | [`await terra.diagnostics.state()`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#diagnostics.state), which answers `.linkRevoked` when Terra no longer accepts the device's link                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `postActivity`, `postBody`, `postNutrition`                                  | [`terra.activity.log`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#activitymetrics.log), [`terra.body.log`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#bodymetrics.log), [`terra.nutrition.log`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#nutritionmetrics.log). These log samples your app measured itself. Writing Terra's own payloads back into Apple Health is not available                                                                                                                                                                                                                 |
| `setIgnoredSources([...])`                                                   | Not available. The SDK uploads data from every app the person granted access to. Merging it with other connections is up to your backend                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `enablePlannedWorkoutBackendSync`, `syncPlannedWorkoutsFromBackend`          | [`connection.workouts.requestScheduling()`](https://docs.tryterra.co/mobile-sdks/planned-workouts-apple-watch.md#ask-for-scheduling-permission), once. After that every sync run puts the person's plans on their Apple Watch. There is no sync call to make. See [Planned workouts on Apple Watch](https://docs.tryterra.co/mobile-sdks/planned-workouts-apple-watch.md)                                                                                                                                                                                                                                                                    |
| FreeStyleLibre (`activateSensor`, `readGlucoseData`)                         | Removed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Disconnect through `deauthenticateUser` on your backend                      | Still works. On the device, [`connection.disconnect()`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#connection.disconnect) also forgets the link and revokes its key                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

Every call is `async` and throws a [`TerraError`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terraerror). Each case has a stable [`code`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terraerror.code) and an [`isRetryable`](https://docs.tryterra.co/reference/mobile-sdks/ios-sdk-2#terraerror.isretryable) answer.

### Before and after

{% tabs %}
{% tab title="1.x" %}
{% code title="YourApp.swift" %}

```swift
import TerraiOS

Terra.instance(devId: "<DEV_ID>", referenceId: "<USER_ID>") { manager, error in
    guard let manager else { return }
    if manager.getUserId(type: .APPLE_HEALTH) == nil {
        manager.initConnection(type: .APPLE_HEALTH, token: tokenFromBackend,
                               customReadTypes: [], schedulerOn: true) { success, error in }
    }
}

// AppDelegate
Terra.setUpBackgroundDelivery()
```

{% endcode %}
{% endtab %}

{% tab title="2.x" %}
{% code title="YourApp.swift" %}

```swift
import TerraSDK

let terra = Terra(devID: "<DEV_ID>") { try await backend.mintTerraToken() }

// At launch, before the first await
BackgroundSync.register(terra: terra)

// When the user taps "Connect Apple Health"
try await terra.connect(.health, for: .reference(user.id))
try await terra.permissions.request(read: [.daily, .sleep, .activity, .body])
```

{% 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 %}
