> For the complete documentation index, see [llms.txt](https://docs.ayetstudios.com/v/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ayetstudios.com/v/product-docs/offerwall/sdk-integrations-v2/ios-sdk-v2.md).

# iOS SDK (v2)

The iOS SDK allows you to easily monetize your app and reward your users with in-app currency. Your users get access to our offers and surveys, allowing them to earn rewards for completing offers.

{% hint style="info" %}

### Updates History

**2025-12-02: v1.0.0** - Release the iOS SDK v2
{% endhint %}

## Eligible Placement & AdSlot Combinations <a href="#eligible-placement-and-adslot-combinations" id="eligible-placement-and-adslot-combinations"></a>

The table below shows all Placement & AdSlot Type combinations that allow you to utilize the iOS SDK integration.

| Placement Type | AdSlot Type   |
| -------------- | ------------- |
| iOS            | Offerwall     |
| iOS            | Surveywall    |
| iOS            | Offerwall API |

{% hint style="danger" %}
If you integrate the iOS SDK while using a different Placement & AdSlot combination in the ayeT-Studios dashboard, you won't be able to initialize the SDK.
{% endhint %}

## Demo App

{% embed url="<https://github.com/ayetstudios/ios-sdk-v2-demo-app>" %}

## Getting Started

Before you start with the integration, make sure you have:

* [x] Created an Account
* [x] Added a Placement
* [x] Added an AdSlot

You can find more details here:

{% content-ref url="/pages/W7CE6bNya8L7RoaXXY21" %}
[Dashboard Setup](/v/product-docs/dashboard-setup.md)
{% endcontent-ref %}

{% hint style="warning" %}
Make sure to use the correct package name that you intend to use for your final app. Alternatively, create a test placement with a different package name that matches the package name of your test app.

If package name of your placement and your actual app don't match, you can't initialize the SDK.
{% endhint %}

## Adding the SDK Dependency

To integrate the iOS SDK into your project, add the package dependency to your app.

In Xcode, with your project open, click **File** and **Add Package Dependencies...**

<figure><img src="https://4086115684-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQYkbOrUvRXzrXgEDF9qs%2Fuploads%2FepEcJYJiYNv0AZwq9vin%2Fimage.png?alt=media&amp;token=be1b7002-1ae7-4412-89cf-c13baf76aa56" alt=""><figcaption></figcaption></figure>

Enter the repository URL (`https://github.com/ayetstudios/ios-sdk-v2-repo`) in the search bar and click **Add Package**:

<figure><img src="https://4086115684-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQYkbOrUvRXzrXgEDF9qs%2Fuploads%2Fh9FWojJ0sknTZMPV7o6H%2Fimage.png?alt=media&amp;token=9a296c01-c634-47d6-93b0-47dae1285da5" alt=""><figcaption></figcaption></figure>

Select the target for your app, then click **Add Package** again:

<figure><img src="https://4086115684-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQYkbOrUvRXzrXgEDF9qs%2Fuploads%2FXbaj2oRshGOIOQZ2DDdS%2Fimage.png?alt=media&amp;token=b9ef3199-27cb-4ff3-86a7-42cbf5b75297" alt=""><figcaption></figcaption></figure>

## Import and initialize the SDK <a href="#initialize-the-sdk-and-managed-user-balances" id="initialize-the-sdk-and-managed-user-balances"></a>

In this step, we will import and initialize the SDK in the app.

{% hint style="info" %}
**Note:** The `externalIdentifier` passed in the init call is the user's identifier on your end. This will be accessible in the conversion callbacks through the `{external_identifier}` parameter. The `placementId` is the unique ID assigned to your placement when it's created through our dashboard.
{% endhint %}

First, import the library:

```swift
import AyetSDK           
```

Then, call the `AyetSDK.shared.initialize` method:

```swift
@main
struct iosSdkV2DemoAppApp: App {
    init() {
        AyetSDK.shared.initialize(placementId: YOUR_PLACEMENT_ID, externalIdentifier: "USER_EXTERNAL_IDENTIFIER")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

## Show the Offerwall

To show the offerwall, simply call the `showOfferwall` method:

```swift
await AyetSDK.shared.showOfferwall(adSlotName: "YOUR_OFFERWALL_ADSLOT_NAME")
```

{% hint style="info" %}
The `YOUR_OFFERWALL_ADSLOT_NAME` parameter can be found by clicking on the adslot on your dashboard. This is only available on **Offerwall** adslots.
{% endhint %}

## Conversion Callbacks & Currency Handling <a href="#conversion-callbacks-and-currency-handling" id="conversion-callbacks-and-currency-handling"></a>

Learn about:

* Setting up callbacks
* IP Whitelists
* Securing callbacks using HMAC Security Hash
* Testing callbacks

Click on the link below:

{% content-ref url="/pages/5sxVWIW1fto5Mmv1JxeJ" %}
[Callbacks & Testing](/v/product-docs/callbacks-and-testing.md)
{% endcontent-ref %}

## Additional Methods

## Fetch Offers

To fetch a list of all offers in JSON format, simply call the `getOffers` method:

```kt
if let offersJson = await AyetSDK.shared.getOffers(adSlotName: "YOUR_OFFERWALL_API_ADSLOT_NAME") {
    print("Offers received: \(offersJson)")
} else {
    print("Failed to get offers - null response")
}
```

{% hint style="info" %}
The `YOUR_OFFERWALL_API_ADSLOT_NAME` parameter can be found by clicking on the adslot on your dashboard. This is only available on **Offerwall API** adslots.
{% endhint %}

## Show Reward Status

The Reward Status page allows users to see their clicked and in-progress offers and allows users to request support / submit tickets. The reward status is also part of the offerwall and the surveywall. To show the reward status page stand-alone, simply call the `showRewardStatus` method:

```swift
await AyetSDK.shared.showRewardStatus()
```

## Show the Surveywall

To show the surveywall, simply call the `showSurveywall` method:

<pre class="language-swift"><code class="lang-swift"><strong>await AyetSDK.shared.showSurveywall(adSlotName: "YOUR_SURVEYWALL_ADSLOT_NAME")
</strong></code></pre>

{% hint style="info" %}
The `YOUR_SURVEYWALL_ADSLOT_NAME` parameter can be found by clicking on the adslot on your dashboard. This is only available on **Surveywall** adslots.
{% endhint %}

## Set custom parameters

Set custom parameters for callbacks. Set up to 5 custom parameters.

```swift
AyetSDK.shared.setTrackingCustom1("custom1")
AyetSDK.shared.setTrackingCustom2("custom2")
AyetSDK.shared.setTrackingCustom3("custom3")
AyetSDK.shared.setTrackingCustom4("custom4")
AyetSDK.shared.setTrackingCustom5("custom5")
```

{% hint style="info" %}
Note: Custom parameters must also be added to your callback URL to receive them in your S2S callbacks.
{% endhint %}

More information here:

{% content-ref url="/pages/4uQiMxtgnAayAHR8ZeXt" %}
[Offerwall Callbacks](/v/product-docs/callbacks-and-testing/callbacks/offerwall-callbacks.md)
{% endcontent-ref %}

## Set Age and Gender

Additionally, you may optionally pass user age and gender to us. This can help us match users to the best and most appropriate offers for them.

```swift
AyetSDK.shared.setGender(.male)
AyetSDK.shared.setGender(.female)
AyetSDK.shared.setAge(25)
```