> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stringboot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from 2.x

> Move your iOS app from Stringboot SDK 1.x or 2.x to 3.0

***

> [!WARNING]
>
> **This upgrade is required.** The endpoints SDK 1.x and 2.x use now answer `426 Upgrade Required`. Apps built with them keep showing the strings they cached but receive no further updates until you ship a build with SDK 3.0.1 or later.

Apps that only use `StringProvider`, `FAQProvider`, `SBText`, `SBLabel` and the UIKit extensions compile unchanged. Your cached strings, FAQs and Device-ID survive the upgrade.

## 1. Update the package

SDK 3.0 ships as a binary Swift package at a new URL and requires iOS 15 or macOS 12 and Xcode 27 or later. Replace your package dependency with `https://github.com/Stringboot-SDK/stringboot-ios-sdk` and set the requirement to `from: "3.0.1"`:

```swift theme={null}
.package(url: "https://github.com/Stringboot-SDK/stringboot-ios-sdk", from: "3.0.1")
```

See [Installation](https://docs.stringboot.com/ios-sdk/installation.md) for manual installation.

## 2. Use a Client Token

Pass your App's **Client Token** (`sb_...`) as `apiToken`. Create one in the dashboard (see [API Tokens](https://docs.stringboot.com/dashboard-guides/api-tokens.md)). The token travels in the URL path, not in a header. A Figma Plugin Token, or a revoked or expired token, gets `401`.

```swift theme={null}
StringProvider.shared.initialize(
    cacheSize: 1000,
    apiToken: "sb_YOUR_CLIENT_TOKEN",
    baseURL: "https://api.stringboot.com"
)
```

## 3. Review these changes

| Area | What changed |
| :- | :- |
| **Device-ID** | Nothing to do. The 2.x Device-ID is kept, so experiment variants don't change. If you pass `providedDeviceId`, pass it on every launch (3.0 no longer stores it) and make sure it differs per user. |
| **Experiments** | Bucketed on the device. `onExperimentsAssigned` keeps working; add `onExperimentExposure(_:)` to report exposures. It's now called with an **empty dictionary** when the last experiment stops. See [A/B Testing](https://docs.stringboot.com/ios-sdk/ab-testing.md). |
| **FAQs** | Come with the strings. Keep `FAQProvider.shared.initialize(...)` with the same token, and drop separate FAQ syncs on launch. |
| **Periodic sync** | `startPeriodicSync()` checks every 60 seconds. Intervals under 60 are raised to 60. |
| **`refreshFromNetwork(forceRefresh:)`** | `forceRefresh` no longer re-downloads an unchanged Catalog: Catalogs are immutable per version. |
| **Fallback** | A key missing from the selected language now falls back to the App's default language before your app bundle. |
| **Certificate pinning** | New built-in pins; see [Troubleshooting](https://docs.stringboot.com/ios-sdk/troubleshooting.md#certificate-pinning). |

### Removed APIs

`FAQSyncClient`, the Core Data classes (`StringbootDatabase`, `FAQDatabase`, `CachedString`, `CachedFAQEntity`), the old wire models (`MetaData`, `CatalogData`, `DeltaUpdatesResponse`, and others) and `StringbootAPI`'s v1/v2 methods.

## What happens to installed apps

On the first launch after the upgrade, the SDK migrates once and never crashes doing it:

* Strings and FAQs cached by 2.x are kept and served offline until the first successful sync replaces them. The old store is then deleted. If it can't be read, it's discarded and the app starts like a fresh install (bundle strings until the first sync).
* Obsolete settings are removed. The Device-ID (`sb_device_id`) and the selected language are kept.

## Checklist

* [ ] The package points at `https://github.com/Stringboot-SDK/stringboot-ios-sdk` with `from: "3.0.1"`
* [ ] The deployment target is iOS 15 / macOS 12 or later, and you build with Xcode 27 or later
* [ ] `apiToken` is a Client Token starting with `sb_`
* [ ] `startPeriodicSync()` is called if you want edits while the app stays open
* [ ] Analytics code handles an empty assignments dictionary
* [ ] A fresh install shows your strings, and an edit in the dashboard appears within about two minutes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.