Skip to main content
The SideShift App SDK is the SideShift Pixel for an iOS app. A creator’s SideChat link opens a SideShift page that sends the person to the App Store. When your app first opens, the SDK ties that install to the link. Your server then reports each paid order, and SideShift credits the sale to the creator, campaign and video. The SDK uses no advertising ID and no device fingerprint. Link taps, the pasteboard, universal links, creator codes and App Store purchases need no App Tracking Transparency prompt. Only email and phone matching waits for tracking permission.

1. Add your app in SideShift

In Settings → Ads & Ecom, find SideShift App SDK and choose Add App. Paste your App Store link: SideShift fills in the app’s name, icon, bundle ID and website from the App Store. You can also enter them yourself. The app’s Setup tab then walks through each step below with your keys already filled in, and shows a green check as each one starts working. The SDK key (ss_pixel_…) goes in the app and is public, like a pixel code. The Orders API key (ss_orders_…) stays on your server. The app shows Setup required until the SDK sends its first event and you connect App Store Connect. Both steps are required, because Apple sends renewals and refunds to SideShift only for an app with App Store Connect connected.

2. Install the SDK

Add the Swift package to your app: in Xcode choose File → Add Package Dependencies and paste https://github.com/SideShiftApp/sideshift-ios-sdk. The repository’s README is the full developer guide. Then configure it when the app launches:
The SDK sends app_install on the first open and app_open when the app comes back to the foreground. Events are queued on the device and retried when the network returns.
  1. A person taps a creator’s link. It opens the SideShift app link page, https://app.sideshift.app/a/<code>.
  2. Get the app copies the link and opens your App Store page.
  3. On the first open, the SDK reads the copied link. iOS may ask the person to allow the paste. The install is credited to that link.
  4. If the person already has your app, I already have it opens your website with ss and ss_click in the URL. With universal links set up on that domain, iOS opens your app, and SideShift.handle(_:) credits the open to the link.
SideShift credits a link only when the open carries the click ID that the link page recorded for that link in the last 7 days. A URL with just a code, such as ?ss=<code> without ss_click, is not credited. One link tap credits one install. The first install that opens with a click ID keeps it for its install and its later opens. Another install that opens with the same click ID is recorded, but it is not credited to the link. Without a link, an install is recorded but credited to no one. To turn off the pasteboard check, pass SideShift.Options(readsPasteboardOnInstall: false) to configure. Only already-installed apps opened through universal links are then credited.

More ways to credit an install

Every method below is exact. SideShift never guesses from a device’s details.

Email and phone matching

When a person signs up or logs in, tell SideShift who they are. The SDK hashes the email and phone on the device before sending them:
Pass the Instagram username if your app asks for it or offers Instagram login. If a creator’s SideChat DM went to that Instagram account in the last 7 days, the install is credited to that creator, with no email or paste needed. Apple’s rules treat this matching as tracking. By default, the SDK sends identify only after the person allows tracking in the App Tracking Transparency prompt. The SDK never shows the prompt. Your app asks with ATTrackingManager.requestTrackingAuthorization. Until the person allows tracking, the SDK keeps the latest hashes on the device and sends them at the next launch or foreground after permission. To send identify without tracking permission, pass SideShift.Options(identityNeedsTrackingPermission: false) to configure. Do this only if your own App Store privacy review supports it. SideShift gets the email two ways:
  • In the SideChat DM. In the campaign’s SideChat settings, choose Ask for their email, so the opening message asks people to reply with their email for the link. A reply with an email gets the link, and SideShift keeps only its hash.
  • On the link page, which has an optional email field.
If the person gave the same email either way in the last 7 days, the install is credited to that creator’s link, even without a paste or a universal link, on any device. If the install came through a link after that DM or link page visit, the later link keeps the credit. If another install already holds the tap of that link page visit, the email does not credit this install.

The Paste button

Apple’s system Paste button reads the copied link with no “Allow Paste” prompt. Put it in onboarding, for example next to “Got here from a creator? Tap to claim their offer”:
It needs iOS 16 or later.

Creator codes

A brand can give each creator link a code, such as JANE20, when it creates the link. If your app has a code field, pass what the person types:

See how much is matched

The app’s Tracking tab lists each creator’s link with the installs SideShift matched by any of these methods. With App Store Connect connected, it also shows Apple’s download count and the share that was matched.

App Store installs from Apple

Apple can also count installs per creator link, without the SDK. In the app’s Tracking tab, under App Store installs, connect App Store Connect:
  • Provider token: the number after pt= in any campaign link you make in App Store Connect → App Analytics → Campaigns.
  • App Store Connect API key: in Users and Access → Integrations → App Store Connect API, create a key with the App Manager or Sales and Reports role. Enter its issuer ID and key ID, and paste the .p8 file.
SideShift uses the key to read the app’s bundle ID from Apple. If the key cannot read it, or it is not the bundle ID of the app in SideShift, SideShift refuses the key. The link page then sends each tap to your App Store page as a campaign link, with the link’s code as the campaign (ct). SideShift reads Apple’s App Store Installations and Deletions report every few hours and shows first-time downloads and redownloads per creator. Apple reports a day or two later, counts only people who share analytics with developers, and leaves out rows under five people, so these counts run lower than real installs. Orders are credited by the SDK.

App Store purchases and renewals

The SDK sends every App Store purchase it sees, as Apple signed it: new purchases, purchases on other devices, renewals and refunds. SideShift checks Apple’s signature and your bundle ID, so these are verified sales with no server of your own. Call SideShift.track(result) right after product.purchase() to send a purchase at once instead of at the next launch:
Renewals happen while your app is closed, so also send SideShift Apple’s App Store Server Notifications (Version 2). In App Store Connect → your app → App Information, set the production server URL to:
If that URL already points to another service, forward the notifications from there instead. Many subscription services can forward them. SideShift sends a notification only to an app with App Store Connect connected, because the key proves that your company owns the bundle ID. Without App Store Connect, SideShift ignores the notifications. Renewals and refunds then arrive only when the SDK sends them. A REFUND_REVERSED notification restores a refunded sale. Who gets credit: a purchase is credited to the last creator link the install came from in the 7 days before it. Every renewal of that subscription stays with the same creator, unless the person comes through another creator’s link in the 7 days before a renewal. Sandbox and TestFlight purchases are recorded as samples and earn no commission.

3. Send orders from your server

Revenue and commissions come only from verified orders: App Store purchases signed by Apple (above), or orders your server sends. A purchase the app reports with trackPurchase is shown but never pays commission. If your server also reports App Store purchases, use Apple’s transaction ID as orderId, so SideShift counts each one once. Pass SideShift.installId to your server, for example with your sign-up or purchase request, and send it as visitorId:
An order is credited to the last SideShift link the install opened from in the 7 days before the order.

Events

Server events

Events that happen on your backend, such as an approval, a payout or a renewal, can be sent with the Orders API key:
SideShift counts an event once per eventId. If the app and your server both send an event, give both the same eventId (pass it to SideShift.track(_:eventId:)), and it is counted once. SideShift writes its own events with IDs that start with click_claim:, identity: or app_store_notification:. An event with an eventId that starts with one of these prefixes returns 400. The SDK sends events by default. If a person opts out, call:
The SDK drops its queued events, stops sending, and tells SideShift, which stops using that install for attribution.