Skip to main content
This guide takes you from a new developer account to a first search on your own iPhone.
Test on a real iPhone with iOS 26 or later. The SDK does not run in the iOS Simulator.

Get access

1

Sign in to the developer dashboard

Go to tryrollup.com/developers and sign in with your email. Rollup sends you a sign-in link. Your first sign-in creates a developer account that waits for Rollup to approve it. While it waits, the dashboard shows “Your access is being reviewed”.
2

Create an app

Once your account is approved, create an app with a name, your Apple Team ID (10 characters) and your app’s bundle ID. The app gets a publishable key that starts with rk_live_.
3

Wait for the app to be approved

A new app also waits for approval. Until Rollup approves it, the server answers every request with the error app_pending. Rollup emails you when your account or app is approved, or if it is not.
The publishable key ships inside your app, so it is not a secret. What proves a request comes from your app is App Attest, which Rollup checks against your Team ID and bundle ID.

Add the SDK

The SDK ships as a binary framework, Rollup.xcframework, that you add with Swift Package Manager or CocoaPods. It requires iOS 26.
In Xcode, choose File, then Add Package Dependencies, and enter the package URL. Add the Rollup library to your app target.
Or add it to Package.swift:
Package.swift
The framework is dynamic, signed by Rollup, and includes its own privacy manifest. Xcode embeds it in your app. Rollup’s enums, such as IndexingState and RollupError.Code, can gain cases in later versions. When you switch over one, include a default or @unknown default case.

Configure your app target

The SDK checks these entries when you call configure, and throws an error that names any that are missing.
1

Photos usage description

Add NSPhotoLibraryUsageDescription to your Info.plist with text that tells the person why your app reads their photos.
2

Background task identifiers

Add both identifiers below to BGTaskSchedulerPermittedIdentifiers. The first lets indexing continue in the background after the person starts it; the second keeps the index up to date later.
3

Background processing mode

Add processing to UIBackgroundModes. In Xcode, this is the Background processing option of the Background Modes capability.
4

App Attest

Add the App Attest capability to your target. configure cannot check for it; without it, the device cannot register, and the first call that needs Rollup’s server throws appAttestFailed, naming the missing capability.
Info.plist
Development-signed builds attest in Apple’s development App Attest environment, which Rollup accepts, so your real key works from your first build on a device.

Configure the SDK

Register the background tasks and configure the SDK when your app starts. registerBackgroundTasks must run before your app finishes launching.
MyApp.swift
By default the SDK indexes the last three months of photos, screenshots and videos, and keeps adding new ones. To change what it indexes, pass IndexOptions. See Index options.

Ask for Photos access

Call requestPhotoAccess from a screen where the person has just chosen to turn the feature on. iOS shows its Photos prompt once.
When the person grants access, the first index starts at once. It downloads about 225 MB of models on first run, then indexes the newest photos first. If the person leaves your app, indexing continues in the background, and iOS shows its progress. See Background indexing. With limited Photos access, the SDK indexes only the photos the person selected.

Watch indexing

indexing.states reports the current state and every change after it.
Search, query and profile work as soon as state.isSearchable is true: the index answers from the photos it holds so far, newest first, while older ones fill in.

Search, ask and fill a profile

search runs on the iPhone. query and profile need a network connection, and each takes a few seconds to about 20 seconds.
Before your app calls query or profile, it must tell the person that results of their photo index are sent to Rollup and its model provider, and get their permission. See Privacy and App Review.

Next steps

Index options

Choose the time window, media and places.

Profile schemas

What a schema can ask for and what comes back.

Keys and revocation

Rotate keys and understand what happens when access stops.

Troubleshooting

Common errors and what they mean.