DocsMobile SDKs

iOS SDK

Show the offerwall in your iOS app. Your server creates a short, single-use session, and the SDK opens the offerwall with it, so no key ever ships inside your app.

How it works

When the user taps your Earn button, your app asks your own server for a session.
Your server calls POST /v1/session with your API key and the user’s ID, and passes the token to the app.
The app calls Sharklio.open(token:). The SDK opens the offerwall in a native screen.
Rewards reach your server through your postback, exactly as with the offerwall link. See Postbacks.

A token works once and for 10 minutes. Create a new one each time the user opens the offerwall. Your API key and your link hash salt stay on your server, so nothing in your app can be used to open another user’s offerwall.

Install

iOS 13 or newer, iPhone and iPad, built with Xcode 16 or newer. The SDK uses only UIKit and WebKit and has no third-party dependencies. It works from Swift, SwiftUI and Objective-C.

Swift Package Manager

In Xcode, choose File, Add Package Dependencies, enter https://sharklio.com/ios/sharklio-ios.git and add the SharklioOfferwall library to your app target. In a Package.swift:

dependencies: [
    .package(url: "https://sharklio.com/ios/sharklio-ios.git", from: "1.0.1"),
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "SharklioOfferwall", package: "sharklio-ios"),
    ]),
]

CocoaPods

pod 'SharklioOfferwall', :podspec => 'https://sharklio.com/ios/1.0.1/SharklioOfferwall.podspec'

Manual

Download SharklioOfferwall-1.0.1.xcframework.zip, unzip it, drag SharklioOfferwall.xcframework into your project and set it to Embed & Sign.

Create a session on your server

POSThttps://api.sharklio.com/v1/session

Send the fields as a form or as JSON, with your API key in the Authorization header. This is the same request as for the Android SDK.

Field	Description
`user_id`requiredstring	The same user ID you receive in postbacks. 1 to 100 characters: letters, numbers, and `. _ @ : + -`.
`sub1` to `sub5`optionalstring	Your own tracking values. They are returned in the postback as `{sub1}` to `{sub5}`.

Errors: 400 invalid_user_id, 401 invalid_api_key, 403 app_not_live or user_blocked (do not show the offerwall), 405 method_not_allowed, 429 rate_limited (retry after the time in the Retry-After header).

Open the offerwall

Call configure once, for example in application(_:didFinishLaunchingWithOptions:), with the App ID from the Integration tab. Then open the offerwall with a fresh token from your server.

import SharklioOfferwall

Sharklio.configure(appId: "YOUR_APP_ID")

// When the user taps Earn, with a token from your server:
Sharklio.open(token: token)

// Or present from a view controller of your choice:
Sharklio.open(token: token, from: self)

Without a view controller, the SDK presents from the top screen of your app, so it also works from SwiftUI:

Button("Earn coins") {
    Task {
        let token = try await api.fetchSharklioToken()
        Sharklio.open(token: token)
    }
}

Objective-C:

@import SharklioOfferwall;

[Sharklio configureWithAppId:@"YOUR_APP_ID"];
[Sharklio openWithToken:token from:self options:nil];

open never throws for offerwall problems. They arrive as events, see Events.

Branding

The top bar of the offerwall screen shows the Sharklio mark, like the offerwall itself, with your offerwall title and colors from the Design tab of your dashboard. When you change them in the dashboard, the SDK picks them up within a few minutes. To set them yourself, pass options. Anything you set wins over the Design tab:

Sharklio.open(token: token, options: SharklioOptions(
    title: "Earn coins",
    toolbarColor: UIColor(red: 0, green: 0.29, blue: 0.73, alpha: 1),
    showLogo: false
))

The offerwall opens full screen. Pass presentation: .sheet to open it as a sheet the user can also swipe down to close.

Events

Sharklio.onClosed = { [weak self] in
    self?.refreshBalance()
}
Sharklio.onError = { error in
    print(error.code.name, error.message)
}

Prefer a delegate? Set Sharklio.delegate (a weak reference) to an object that adopts SharklioDelegate: sharklioDidOpen(), sharklioDidClose() and sharklioDidFail(with:). All events arrive on the main thread.

Event	When
`onOpened`	The offerwall finished loading.
`onClosed`	The user closed the offerwall. A good moment to load the user’s balance from your server.
`onError`	`NOT_INITIALIZED`, `INVALID_APP_ID`, `INVALID_TOKEN`, `TOKEN_EXPIRED_OR_USED`, `NETWORK`, or `UNKNOWN`. Create a new session and try again.

Using Flutter, React Native, or Unity? The Flutter SDK, the React Native SDK, and the Unity SDK bring this SDK with them.

App Store privacy details

The SDK’s privacy manifest lists what the offerwall collects, as described in our privacy policy. In App Store Connect, under App Privacy, add these data types for your app:

Data type	Linked to the user	Used for tracking	Purpose
User ID	Yes	No	App Functionality
Device ID	Yes	No	App Functionality
Coarse Location	Yes	No	App Functionality
Product Interaction	Yes	No	App Functionality

The user ID is the pseudonymous ID your server sends with the session, the device ID is used for fraud prevention, the coarse location comes from the IP address, and product interaction is the offers a user views, starts, and completes. The SDK does not track users across apps and does not use the advertising identifier. Publishing on Android? Fill in Google Play’s Data safety form with the same data types.

What the SDK handles for you

Offers that lead to the App Store open in the App Store app, and other sites open in Safari, so installs are tracked correctly.
The close button returns to your app. Swiping from the left edge goes back inside the offerwall.
If iOS pauses the offerwall in the background, it comes back where the user was, without using the token again.
A locked-down web view: only offerwall pages load inside it, no JavaScript bridge into your app, and camera and microphone requests are denied.
Light and dark mode, larger text sizes and VoiceOver.

Security

Create sessions on your server only. Never put the API key or the link hash salt in your app, because anyone can read an app’s files.
Credit rewards only from the signed postback on your server, never from events in the app. Events can be faked on a user’s device.
Make sure your own endpoint that returns tokens only does so for the signed-in user.

Testing

Before you launch, create a session from your server for a test user ID and open it in a debug build of your app on an iPhone or in the Simulator. Check that the offerwall opens, that an offer opens in the App Store or Safari, and that the close button works. Then send test postbacks from Integration status on the Integration tab of your app to check your server. Test on a normal home or mobile connection: on a VPN or a test device in the cloud, the offerwall shows a block page such as VPN detected instead of offers. See Testing.

Clicks that come through the SDK show as sdk in the {integration} postback macro and in the Reporting API, and as Mobile SDK in your dashboard, like the Android SDK.

Swift package URL

https://sharklio.com/ios/sharklio-ios.git

Create a session

POSTapi.sharklio.com/v1/session

curl -X POST "https://api.sharklio.com/v1/session" \
  -H "Authorization: Bearer $SHARKLIO_API_KEY" \
  -d "user_id=user_1234"

$ch = curl_init('https://api.sharklio.com/v1/session');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query(['user_id' => $userId]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);
$token = json_decode(curl_exec($ch), true)['token'] ?? null;

const res = await fetch('https://api.sharklio.com/v1/session', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHARKLIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user_id: userId }),
});
const { token } = await res.json();

Your API key is in your dashboard under Apps, your app, Integration. Up to 600 requests per minute for each app.

Questions? [email protected]