DocsMobile SDKs

Unity SDK

Show the offerwall in your Unity game on Android and iOS. Your server creates a short, single-use session, and the plugin opens the offerwall with it, so no key ever ships inside your game.

How it works

When the player taps your Earn button, your game asks your own server for a session.
Your server calls POST /v1/session with your API key and the player’s ID, and passes the token to the game.
The game calls Sharklio.Open(token). The plugin 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 player opens the offerwall. Your API key and your link hash salt stay on your server, so nothing in your game can be used to open another player’s offerwall.

Platform	Status
Android	Supported on every Android version your Unity version supports. The plugin uses the Android SDK inside.
iOS 13 or newer	Supported. The plugin uses the iOS SDK inside. Build with Xcode 16 or newer.
Unity Editor, desktop, WebGL	Not supported. `Open` checks the app ID and the token and then reports `Unsupported`, so you can test your flow in the Editor.

Install

Unity 2022.3 LTS or Unity 6 (6000.0) or newer. The plugin is in the Sharklio package registry. Add the registry and the package to Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "Sharklio",
      "url": "https://sharklio.com/upm",
      "scopes": ["com.sharklio"]
    }
  ],
  "dependencies": {
    "com.sharklio.offerwall": "1.0.0"
  }
}

You can also add the registry in Project Settings, Package Manager, and then install Sharklio Offerwall from My Registries in the Package Manager window. Prefer a file? Download sharklio-unity-offerwall-1.0.0.tgz and choose Install package from tarball in the Package Manager.

There is nothing else to set up:

Android: when Unity generates the Gradle project, the plugin adds the Sharklio Maven repository (only for the com.sharklio group), the Android SDK and its R8 rule. This also works for exported projects and custom Gradle templates.
iOS: the plugin brings the Sharklio iOS SDK with it and adds it to the Xcode project, linked and embedded. Set Target minimum iOS Version to 13.0 or higher in Player Settings; the build stops with a clear message otherwise.

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 Init once with the App ID from the Integration tab. Then open the offerwall with a fresh token from your server.

using SharklioOfferwall;
using UnityEngine;

public class EarnButton : MonoBehaviour
{
    void Awake()
    {
        Sharklio.Init("YOUR_APP_ID");
    }

    // Call this with a fresh token from your server.
    public void ShowOfferwall(string token)
    {
        Sharklio.Open(token);
    }
}

Open never throws for offerwall problems. They arrive as events, see Events. The package has an Offerwall demo sample with an Earn button that gets a token from your server: Window, Package Manager, Sharklio Offerwall, Samples.

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. To set the title or color yourself, or to hide the mark, pass options:

Sharklio.Open(token, new SharklioOptions(
    title: "Earn coins",
    toolbarColor: new Color32(0x00, 0x4A, 0xBB, 0xFF),
    showLogo: false));

Events

All events are raised on the Unity main thread, so you can update your UI directly.

void OnEnable()
{
    Sharklio.OnClosed += RefreshBalance;
    Sharklio.OnError += HandleError;
}

void OnDisable()
{
    Sharklio.OnClosed -= RefreshBalance;
    Sharklio.OnError -= HandleError;
}

void HandleError(SharklioError error)
{
    Debug.LogWarning(error.CodeName + ": " + error.Message);
}

Event	When
`OnOpened`	The offerwall finished loading. On Android your game is paused while the offerwall is open, so this event can arrive when the player returns.
`OnClosed`	The player closed the offerwall. A good moment to load the player’s balance from your server.
`OnError`	`NotInitialized`, `InvalidAppId`, `InvalidToken`, `TokenExpiredOrUsed`, `Network`, `Unsupported`, or `Unknown`. `CodeName` gives the name the native SDKs use, for example `TOKEN_EXPIRED_OR_USED`. Create a new session and try again.

App Store and Google Play privacy

The iOS SDK inside the plugin has a privacy manifest that lists what the offerwall collects, as described in our privacy policy. In App Store Connect, under App Privacy, and in Google Play’s Data safety form, add these data types for your game:

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 player views, starts, and completes. The SDK does not track players across apps and does not use the advertising identifier. In Google Play’s Data safety form, the same data types are called User IDs, Device or other IDs, Approximate location, and App interactions.

Security

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

Testing

Before you launch, create a session from your server for a test user ID and open it in a development build on an Android phone, an iPhone, or the iOS Simulator. Check that the offerwall opens, that an offer opens in the store or the browser, and that the back and close buttons work. 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 plugin show as sdk in the {integration} postback macro and in the Reporting API, and as Mobile SDK in your dashboard, like the Android and iOS SDKs.

Changelog

1.0.0: first release. Sharklio.Init and Sharklio.Open with the same checks and error codes as the Android and iOS SDKs, main-thread events, top bar options, the Android SDK 1.1.0 added to Gradle automatically, the iOS SDK 1.0.1 bundled and embedded automatically, and the Offerwall demo sample.

License

The plugin is free to use under the Apache License 2.0. The license file is in the package.

Packages/manifest.json

"scopedRegistries": [
  {
    "name": "Sharklio",
    "url": "https://sharklio.com/upm",
    "scopes": ["com.sharklio"]
  }
],
"dependencies": {
  "com.sharklio.offerwall": "1.0.0"
}

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=player_1234"

$ch = curl_init('https://api.sharklio.com/v1/session');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query(['user_id' => $playerId]),
    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: playerId }),
});
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]