# Unity Ads iOS SDK API reference - Swift

> Access the Unity Ads SDK public API reference to view available classes, methods, and properties you can use in Swift to integrate and control ad behavior in your iOS app.

Use this reference for the Unity Ads Android SDK API in Swift as you integrate Unity Ads into your iOS applications.

Before using this API, ensure that you've imported the `UnityAds` library to enable monetization in your app. Refer to [Import the UnityAds library](/ads-ios/4.19.0/sdk-integration/import-library.md) for more information.

## Classes

### UADSBannerAd

The `UADSBannerAd` class manages the loading and showing of banner ads.

### load(\_:completion)

1. **Swift**

   ```swift
   public class UADSBannerAd: NSObject {
       public static func load(_ configuration: UADSBannerLoadConfiguration,
                                 completion: @escaping (UADSBannerAd?, UnityAdsError?) -> Void)
   }
   ```

Loads a banner ad with the specified configuration.

| **Parameters** | **Description**                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| configuration  | The options for loading the banner ad.                                                                                                               |
| completion     | A callback that gets called when the banner is loaded. Returns the loaded UADSBannerAd instance if successful, or an UnityAdsError if loading fails. |

### onAdExpired

1. **Swift**

   ```swift
   public var onAdExpired: ((UADSBannerAd) -> Void)?
   ```

A callback that gets triggered when the ad expires. Set this property to be notified when a loaded banner ad expires and is no longer valid.

### view

1. **Swift**

   ```swift
   public class UADSBannerAd: UIView {
       public var view: UIView
   }
   ```

A view property that provides access to the banner ad instance. Use this property to insert the banner ad within your app's existing view hierarchy at the desired location.

### UADSBannerView

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSBannerAd`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsbannerad) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSBannerView` was the previous class for loading and displaying banner ads.

### UADSBannerViewDelegate

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSBannerAdDelegate`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsbanneraddelegate) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSBannerViewDelegate` was the previous delegate protocol for handling banner ad events.

## UADSBannerLoadConfiguration

The `UADSBannerLoadConfiguration` class encapsulates the options needed to load banner ads. This includes specifying the placement ID, banner size, optional ad markup, optional delegate, and any additional parameters.

1. **Swift**

   ```swift
   public class UADSBannerLoadConfiguration: NSObject {
       @objc public private(set) var placementId: String
       @objc public private(set) var adMarkup: String?
       @objc public private(set) var bannerSize: CGSize
       @objc public private(set) var delegate: UADSBannerAdDelegate
       @objc public private(set) var mediationAdUnitId: String?
       @objc public private(set) var mediationInfo: UADSMediationInfo?
       @objc public private(set) var extras: [String: String]
   }
   ```

| **Property**        | **Description**                                                            | **Required** |
| ------------------- | -------------------------------------------------------------------------- | ------------ |
| `placementId`       | The placement ID defined in the Unity Monetization Dashboard.              | Yes          |
| `adMarkup`          | Ad markup data that's used when loading an ad through bidding.             | No           |
| `bannerSize`        | The size of the banner ad.                                                 | Yes          |
| `delegate`          | Delegate to handle banner ad events.                                       | Yes          |
| `mediationAdUnitId` | The ad unit or placement ID defined in your mediation partner's dashboard. | No           |
| `mediationInfo`     | Specifies details about your mediation integration.                        | No           |
| `extras`            | Additional custom key–value pairs.                                         | No           |

## UADSBannerLoadConfigurationBuilder

Use `UADSBannerLoadConfigurationBuilder` to create and return an instance of the `UADSBannerLoadConfiguration` class.

### init(placementId, bannerSize, delegate)

1. **Swift**

   ```swift
   public init(placementId: String,
               bannerSize: CGSize,
               delegate: UADSBannerAdDelegate)
   ```

Creates a new instance of `UADSBannerLoadConfigurationBuilder`.

| **Property**  | **Description**                                               | **Required** |
| ------------- | ------------------------------------------------------------- | ------------ |
| `placementId` | The placement ID defined in the Unity Monetization Dashboard. | Yes          |
| `bannerSize`  | The size of the banner ad.                                    | Yes          |
| `delegate`    | Delegate to handle banner ad events.                          | Yes          |

**Returns**: An instance of `UADSBannerLoadConfigurationBuilder`.

### with(adMarkup:)\_

1. **Swift**

   ```swift
   public func with(adMarkup: String) -> Self
   ```

Adds an adMarkup to the `UADSBannerLoadConfigurationBuilder`.

| **Parameter** | **Description**                                                |
| ------------- | -------------------------------------------------------------- |
| adMarkup      | Ad markup data that's used when loading an ad through bidding. |

**Returns**: The updated `UADSBannerLoadConfigurationBuilder` instance.

### with(mediationAdUnitId:)\_

1. **Swift**

   ```swift
   public func with(mediationAdUnitId: String) -> Self
   ```

Adds a mediation ad unit ID to the `UADSBannerLoadConfigurationBuilder`.

| **Parameter**     | **Description**                                                            |
| ----------------- | -------------------------------------------------------------------------- |
| mediationAdUnitId | The ad unit or placement ID defined in your mediation partner's dashboard. |

**Returns**: The updated `UADSBannerLoadConfigurationBuilder` instance.

### with(mediationInfo:)\_

1. **Swift**

   ```swift
   public func with(mediationInfo: UADSMediationInfo) -> Self
   ```

Adds mediation information to the `UADSBannerLoadConfigurationBuilder`.

| **Parameter** | **Description**                                                           |
| ------------- | ------------------------------------------------------------------------- |
| mediationInfo | Details about the mediation integration (name, version, adapter version). |

**Returns**: The updated `UADSBannerLoadConfigurationBuilder` instance.

### with(extras:)\_

1. **Swift**

   ```swift
   public func with(extras: [String: String]) -> Self
   ```

Adds extra key–value parameters to the `UADSBannerLoadConfigurationBuilder`.

| **Parameter** | **Description**                       |
| ------------- | ------------------------------------- |
| extras        | Custom parameters for banner loading. |

**Returns**: The updated UADSBannerLoadConfigurationBuilder instance.

### build()\_

1. **Swift**

   ```swift
   public func build() -> UADSBannerLoadConfiguration
   ```

Builds and returns a `UADSBannerLoadConfiguration` instance.

**Returns**: An instance of `UADSBannerLoadConfiguration`.

### UADSBannerLoadOptions

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSBannerLoadConfiguration`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsbannerloadconfiguration) and [`UADSBannerLoadConfigurationBuilder`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsbannerloadconfigurationbuilder) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSBannerLoadOptions` was the previous class for specifying banner load options.

## UADSInitializationConfiguration

1. **Swift**

   ```swift
   public class UADSInitializationConfiguration: NSObject {
       @objc public private(set) var gameId: String
       @objc public private(set) var isTestModeEnabled: Bool
       @objc public private(set) var logLevel: UADSLogLevel
       @objc public private(set) var mediationInfo: UADSMediationInfo?
       @objc public private(set) var extras: [String: String]
   }
   ```

The `UADSInitializationConfiguration` class creates an object consisting of essential information about your app required to initialize the Unity Ads SDK.

| **Property**        | **Description**                                                                          | **Required** |
| ------------------- | ---------------------------------------------------------------------------------------- | ------------ |
| `gameId`            | Your unique game identifier from the Unity Ads Monetization dashboard.                   | Yes          |
| `isTestModeEnabled` | A boolean that enables test mode. When true, only test ads are shown. Defaults to false. | No           |
| `logLevel`          | Specifies the level of detail for log output. Defaults to INFO.                          | No           |
| `mediationInfo`     | An object that contains information about your mediation integration.                    | No           |
| `extras`            | A map of additional key–value parameters for custom configuration.                       | No           |

## UADSInitializationConfigurationBuilder

Use `UADSInitializationConfigurationBuilder` to create and return an instance of the `UADSInitializationConfiguration` class.

### Initialize

1. **Swift**

   ```swift
   public static func initialize(_ configuration: UADSInitializationConfiguration,
                                 completion: @escaping (UnityAdsError?) -> Void)
   ```

Initializes the Unity Ads SDK with a specified configuration. The completion handler is called when initialization completes with either success or failure.

| **Parameter** | **Description**                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| configuration | The UADSInitializationConfiguration object that contains the necessary settings to initialize the SDK.                                             |
| completion    | The completion callback is called upon completion, indicating success or detailing the reason for failure with an error message and an error code. |

### init(gameId:)\_

1. **Swift**

   ```swift
   public init(gameId: String)
   ```

Creates a new instance of `UADSInitializationConfigurationBuilder`.

| **Parameter** | **Description**                                                               |
| ------------- | ----------------------------------------------------------------------------- |
| gameId        | Unique identifier for a game, given by Unity Ads admin tools or Unity editor. |

**Returns**: An instance of `UADSInitializationConfigurationBuilder`.

### with(testMode:)\_

1. **Swift**

   ```swift
   public func with(testMode: Bool) -> Self
   ```

Sets the test mode.

| **Parameter** | **Description**                                                       |
| ------------- | --------------------------------------------------------------------- |
| testMode      | Set this flag to `true` to indicate test mode and show only test ads. |

**Returns**: The updated `UADSInitializationConfigurationBuilder` instance.

### with(logLevel:)\_

1. **Swift**

   ```swift
   public func with(logLevel: UADSLogLevel) -> Self
   ```

Sets the log level, which defines the amount of detail included in logs, from none to full debug information.

| **Parameter**             | **Description**                           |
| ------------------------- | ----------------------------------------- |
| [logLevel](#uadsloglevel) | Specifies the detail level of log output. |

**Returns**: The updated `UADSInitializationConfigurationBuilder` instance.

### with(mediationInfo:)\_

1. **Swift**

   ```swift
   public func with(mediationInfo: UADSMediationInfo) -> Self
   ```

Sets the mediation information, which provides details about your app's mediation integration, including mediation name, version, and adapter version.

| **Parameter** | **Description**                                     |
| ------------- | --------------------------------------------------- |
| mediationInfo | Specifies details about your mediation integration. |

**Returns**: The updated `UADSInitializationConfigurationBuilder` instance.

### with(extras:)\_

1. **Swift**

   ```swift
   public func with(extras: [String: String]) -> Self
   ```

Sets additional parameters.

| **Parameter** | **Description**                                      |
| ------------- | ---------------------------------------------------- |
| extras        | Additional key–value pairs for custom configuration. |

**Returns**: The updated `UADSInitializationConfigurationBuilder` instance.

### build()

1. **Swift**

   ```swift
   public func build() -> UADSInitializationConfiguration
   ```

Builds and returns a `UADSInitializationConfiguration` instance.

**Returns**: An instance of `UADSInitializationConfiguration`.

## UADSInterstitialAd

The `UADSInterstitialAd` class manages the loading and showing of full-screen interstitial ads.

### load(\_:completion)

1. **Swift**

   ```swift
   public class UADSInterstitialAd: NSObject {
       public static func load(_ configuration: UADSLoadConfiguration,
                                 completion: @escaping (UADSInterstitialAd?, UnityAdsError?) -> Void)
   }
   ```

Loads an interstitial ad with the specified configuration.

| **Parameters** | **Description**                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| configuration  | An instance of UADSLoadConfiguration containing the ad loading options.                                                                                      |
| completion     | A callback that gets called when the loading process is finished. Returns a UADSInterstitialAd instance if successful, or an UnityAdsError if loading fails. |

### show(\_:delegate:)

1. **Swift**

   ```swift
   public class UADSInterstitialAd: NSObject {
       public func show(_ configuration: UADSShowConfiguration? = nil,
                          delegate: UADSInterstitialShowDelegate)
   }
   ```

Displays the loaded interstitial ad.

| **Parameter** | **Description**                                                            |
| ------------- | -------------------------------------------------------------------------- |
| configuration | Optional configuration for showing the ad.                                 |
| delegate      | A delegate conforming to UADSInterstitialShowDelegate to handle ad events. |

### onAdExpired

Register a callback that gets triggered when the ad expires.

1. **Swift**

   ```swift
   public class UADSInterstitialAd: NSObject {
       public var onAdExpired: ((UnityAd) -> Void)?
   }
   ```

## UADSLoadConfiguration

The `UADSLoadConfiguration` class encapsulates the options needed to load Unity ads. This includes specifying the placement ID, optional ad markup, and any additional parameters.

1. **Swift**

   ```swift
   public class UADSLoadConfiguration: NSObject {
       @objc public private(set) var placementId: String
       @objc public private(set) var adMarkup: String?
       @objc public private(set) var mediationAdUnitId: String?
       @objc public private(set) var mediationInfo: UADSMediationInfo?
       @objc public private(set) var extras: [String: String]
   }
   ```

Creates a new instance of `UADSLoadConfiguration`.

| **Property**        | **Description**                                                                             | **Required** |
| ------------------- | ------------------------------------------------------------------------------------------- | ------------ |
| `placementId`       | The placement ID defined in the Unity Monetization Dashboard.                               | Yes          |
| `adMarkup`          | Ad markup data that's used when loading an ad through bidding. If it's nil, it's waterfall. | No           |
| `mediationAdUnitId` | The placement ID used in your mediation partner's dashboard.                                | No           |
| `mediationInfo`     | Specifies details about your mediation integration.                                         | No           |
| `extras`            | Additional custom key–value pairs for configuration.                                        | No           |

| **Note:** The adMarkup property is required for all bidding implementations. For waterfall implementations, you can set adMarkup to nil. |
| ---------------------------------------------------------------------------------------------------------------------------------------- |

## UADSLoadConfigurationBuilder

Use `UADSLoadConfigurationBuilder` to create and return an instance of the `UADSLoadConfiguration` class.

### init(placementId:)

1. **Swift**

   ```swift
   public init(placementId: String)
   ```

Creates a new instance of `UADSLoadConfigurationBuilder`.

| **Parameter** | **Description**                                               |
| ------------- | ------------------------------------------------------------- |
| `placementId` | The placement ID defined in the Unity Monetization Dashboard. |

**Returns**: An instance of `UADSLoadConfigurationBuilder`.

### with(adMarkup:)\_

1. **Swift**

   ```swift
   public func with(adMarkup: String) -> Self
   ```

Adds an adMarkup to the `UADSLoadConfigurationBuilder`.

| **Parameter** | **Description**                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| adMarkup      | Ad markup data that's used when loading an ad through bidding. If nil, the ad request uses waterfall. |

**Returns**: The updated `UADSLoadConfigurationBuilder` instance.

### with(mediationAdUnitId:)\_

1. **Swift**

   ```swift
   public func with(mediationAdUnitId: String) -> Self
   ```

Adds the mediation ad unit ID to the `UADSLoadConfigurationBuilder`.

| **Property**        | **Description**                                              |
| ------------------- | ------------------------------------------------------------ |
| `mediationAdUnitId` | The placement ID used in your mediation partner's dashboard. |

**Returns**: The updated `UADSLoadConfigurationBuilder` instance.

### with(mediationInfo:)\_

1. **Swift**

   ```swift
   public func with(mediationInfo: UADSMediationInfo) -> Self
   ```

Adds mediation information to the `UADSLoadConfigurationBuilder`.

| **Parameter** | **Description**                                                                      |
| ------------- | ------------------------------------------------------------------------------------ |
| mediationInfo | Specifies details about your mediation integration (name, version, adapter version). |

**Returns**: The updated `UADSLoadConfigurationBuilder` instance.

### with(extras:)\_

1. **Swift**

   ```swift
   public func with(extras: [String: String]) -> Self
   ```

Adds extra configuration key–value pairs to the `UADSLoadConfigurationBuilder`.

| **Parameter** | **Description**                                   |
| ------------- | ------------------------------------------------- |
| extras        | A dictionary of custom parameters for ad loading. |

**Returns**: The updated `UADSLoadConfigurationBuilder` instance.

### build()

1. **Swift**

   ```swift
   public func build() -> UADSLoadConfiguration
   ```

Builds and returns a `UADSLoadConfiguration` instance.

**Returns**: An instance of `UADSLoadConfiguration`.

### UADSLoadOptions

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSLoadConfigurationBuilder`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsloadconfigurationbuilder) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSLoadOptions` was the previous class for specifying ad load options.

## UADSMediationInfo

Specifies details about your mediation integration.

1. **Swift**

   ```swift
   public class UADSMediationInfo: NSObject {
       public init(name: String, version: String, adapterVersion: String)
   }
   ```

| **Parameters** | **Description**                                                  |
| -------------- | ---------------------------------------------------------------- |
| name           | The name of the mediation platform integrated in your app.       |
| version        | The version of the mediation SDK integrated in your app.         |
| adapterVersion | The version of the Unity Ads adapter for your mediation partner. |

**Returns**: An instance of `UADSMediationInfo`.

### UADSMediationMetaData

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSMediationInfo`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsmediationinfo) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSMediationMetaData` was the previous class for passing mediation partner information.

## Privacy

Privacy is a set of enums and a class offering APIs to manage privacy settings and user consents for Unity Ads. This enables developers to handle various privacy settings and consents that comply with GDPR, PIPL, and other regulations.

1. **Swift**

   ```swift
   public class Privacy: NSObject {
       public static func set(privacy: PrivacyFlag, value: PrivacyValue) {}
       public static func set(consent: PrivacyConsent, value: PrivacyConsentValue) {}
       // to set new flags, throws an exception if writing an existing flag
       public static func setPrivacy(_ flag: String, consent: PrivacyConsentValue) throws {}
       public static func setPrivacy(_ flag: String, value: PrivacyValue) throws {}
   }
   ```

### UADSMetaData

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use the typed privacy methods on [`UnityAds`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#unityads): `setUserConsent()`, `setUserOptOut()`, and `setNonBehavioral()`. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSMetaData` was the previous class for setting GDPR and other privacy-related flags.

## UADSRewardedAd

The `UADSRewardedAd` class manages the loading and showing of rewarded ads.

### load(\_:completion)\_

1. **Swift**

   ```swift
   public class UADSRewardedAd: NSObject {
       public static func load(_ configuration: UADSLoadConfiguration,
                                 completion: @escaping (UADSRewardedAd?, UnityAdsError?) -> Void)
   }
   ```

Loads a rewarded ad with the specified options.

| **Parameters** | **Description**                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| configuration  | An instance of UADSLoadConfiguration containing the ad loading options.                                                              |
| completion     | A callback that gets called when ad loading finishes. Returns a UADSRewardedAd instance if successful, or an Error if loading fails. |

### show(\_:delegate:)

1. **Swift**

   ```swift
   public class UADSRewardedAd: NSObject {
       public func show(_ configuration: UADSShowConfiguration? = nil,
                          delegate: UADSRewardedShowDelegate)
   }
   ```

Displays the loaded rewarded ad.

| **Parameter** | **Description**                                       |
| ------------- | ----------------------------------------------------- |
| configuration | Optional settings for showing the ad.                 |
| delegate      | An optional delegate that handles rewarded ad events. |

### onAdExpired

Register a callback that gets triggered when the ad expires.

1. **Swift**

   ```swift
   public class UADSRewardedAd: NSObject {
       public var onAdExpired: ((UnityAd) -> Void)?
   }
   ```

## UADSShowConfiguration

The `UADSShowConfiguration` class specifies additional parameters that you want to pass in the form of key-value pairs when showing Unity Ads.

1. **Swift**

   ```swift
   public class UADSShowConfiguration: NSObject {
       @objc public private(set) var viewController: UIViewController?
       @objc public private(set) var customRewardString: String?
       @objc public private(set) var extras: [String: String]
   }
   ```

Creates a new instance of `UADSShowConfiguration` with optional additional parameters.

| **Property**         | **Description**                                                                                  | **Required** |
| -------------------- | ------------------------------------------------------------------------------------------------ | ------------ |
| `viewController`     | The view controller used to present the ad.                                                      | No           |
| `customRewardString` | A custom reward identifier for the ad impression.                                                | No           |
| `extras`             | Additional key–value parameters to include when showing the ad. Defaults to an empty dictionary. | No           |

## UADSShowConfigurationBuilder

Use `UADSShowConfigurationBuilder` to create and return an instance of the `UADSShowConfiguration` class.

### \*init()

1. **Swift**

   ```swift
   public init()
   ```

Creates a new instance of UADSShowConfigurationBuilder.

### with(viewController:)

1. **Swift**

   ```swift
   public func with(viewController: UIViewController) -> Self
   ```

Sets the view controller to present the ad from.

| **Parameter**    | **Description**                        |
| ---------------- | -------------------------------------- |
| `viewController` | The view controller presenting the ad. |

**Returns**: The updated UADSShowConfigurationBuilder instance.

### with(customRewardString:)

1. **Swift**

   ```swift
   public func with(customRewardString: String) -> Self
   ```

Sets a custom reward identifier for the ad impression.

| **Parameter**        | **Description**                           |
| -------------------- | ----------------------------------------- |
| `customRewardString` | A unique reward ID for the ad impression. |

**Returns**: The updated `UADSShowConfigurationBuilder` instance.

### with(extras:)

1. **Swift**

   ```swift
   public func with(extras: [String: String]) -> Self
   ```

Adds extra key–value parameters when showing the ad.

| **Parameter** | **Description**                   |
| ------------- | --------------------------------- |
| `extras`      | Custom parameters for ad display. |

**Returns**: The updated `UADSShowConfigurationBuilder` instance.

### build()

1. **Swift**

   ```swift
   public func build() -> UADSShowConfiguration
   ```

Builds and returns a `UADSShowConfiguration` instance.

**Returns**: An instance of `UADSShowConfiguration`.

### UADSShowOptions

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSShowConfigurationBuilder`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsshowconfigurationbuilder) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSShowOptions` was the previous class for specifying ad show options.

## UADSTokenConfiguration

1. **Swift**

   ```swift
   public class UADSTokenConfiguration: NSObject {
       @objc public private(set) var adFormat: UADSAdFormat
       @objc public private(set) var mediationInfo: UADSMediationInfo?
       @objc public private(set) var mediationAdUnitId: String?
       @objc public private(set) var placementId: String?
       @objc public private(set) var bannerSize: CGSize?
       @objc public private(set) var extras: [String: String] = [:]
   }
   ```

The `UADSTokenConfiguration` class creates an object consisting of essential information required to get a bidding token.

| **Property**        | **Description**                                               | **Required** |
| ------------------- | ------------------------------------------------------------- | ------------ |
| `adFormat`          | The type of ad format for which to generate a token.          | Yes          |
| `mediationInfo`     | Specifies details about your mediation integration.           | No           |
| `mediationAdUnitId` | The placement ID used in your mediation partner's dashboard.  | No           |
| `placementId`       | The placement ID defined in the Unity Monetization Dashboard. | No           |
| `bannerSize`        | The size of the banner ad if a token requested a banner ad.   | No           |
| `extras`            | Additional key–value pairs for custom configuration.          | No           |

## UADSTokenConfigurationBuilder

Use `UADSTokenConfigurationBuilder` to create and return an instance of the `UADSTokenConfiguration` class.

### init(adFormat:)

1. **Swift**

   ```swift
   public init(adFormat: UADSAdFormat)
   ```

Creates a new instance of `UADSTokenConfigurationBuilder`.

| **Parameter** | **Description**                                                                             |
| ------------- | ------------------------------------------------------------------------------------------- |
| adFormat      | An instance of UADSAdFormat that specifies the type of ad (interstitial, rewarded, banner). |

**Returns**: An instance of `UADSTokenConfigurationBuilder`.

#### with(mediationInfo:)

1. **Swift**

   ```swift
   public func with(mediationInfo: UADSMediationInfo) -> Self
   ```

Specifies details about your mediation integration.

| **Parameter** | **Description**                                     |
| ------------- | --------------------------------------------------- |
| mediationInfo | Specifies details about your mediation integration. |

**Returns**: The updated `UADSTokenConfigurationBuilder` instance.

### withMediationAdUnitId:\_

1. **Swift**

   ```swift
   public func with(mediationAdUnitId: String) -> Self
   ```

Adds the mediation ad unit ID to the `UADSTokenConfiguration`.

| **Property**        | **Description**                                              |
| ------------------- | ------------------------------------------------------------ |
| `mediationAdUnitId` | The placement ID used in your mediation partner's dashboard. |

**Returns**: The updated `UADSUADSTokenConfigurationBuilder` instance.

### withPlacementId:\_

1. **Swift**

   ```swift
   public func with(placementId: String) -> Self
   ```

Specifies the placement ID defined in the Unity Monetization Dashboard.

| **Parameter** | **Description**                                               |
| ------------- | ------------------------------------------------------------- |
| placementId   | The placement ID defined in the Unity Monetization Dashboard. |

**Returns**: The updated `UADSUADSTokenConfigurationBuilder` instance.

### withBannerSize:\_

1. **Swift**

   ```swift
   public func with(bannerSize: CGSize) -> Self
   ```

Specifies the size of the banner ad if a token requested a banner ad.

| **Parameter** | **Description**                                             |
| ------------- | ----------------------------------------------------------- |
| bannerSize    | The size of the banner ad if a token requested a banner ad. |

**Returns**: The updated `UADSUADSTokenConfigurationBuilder` instance.

#### with(extras:)

1. **Swift**

   ```swift
   public func with(extras: [String: String]) -> Self
   ```

Specifies additional key–value pairs for custom configuration.

| **Parameter** | **Description**                                      |
| ------------- | ---------------------------------------------------- |
| extras        | Additional key–value pairs for custom configuration. |

**Returns**: The updated `UADSTokenConfigurationBuilder` instance.

### build()

1. **Swift**

   ```swift
   public func build() -> UADSTokenConfiguration
   ```

Builds and returns a `UADSTokenConfiguration` instance.

**Returns**: An instance of `UADSTokenConfiguration`.

## UnityAds

The `UnityAds` class is a static class that serves as the primary entry point for the SDK. It handles initialization, token retrieval, and provides access to global SDK properties.

### Initialization

#### initialize(\_, completion:)

Initializes the Unity Ads SDK with a specified configuration. The completion block is called when initialization completes with either success or failure.

1. **Swift**

   ```swift
   public static func initialize(_ configuration: UADSInitializationConfiguration, completion: @escaping (UnityAdsError?) -> Void)
   ```

| **Parameter** | **Description**                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| configuration | The UADSInitializationConfiguration object that contains the required settings to initialize the SDK.              |
| completion    | A callback that gets called when the SDK initialization finishes. Returns a UnityAdsError if initialization fails. |

### GetToken

#### getToken(\_, completion:)

Fetches a bidding token based on the provided `UADSTokenConfiguration` and passes it to the completion block.

1. **Swift**

   ```swift
   public static func getToken(_ configuration: UADSTokenConfiguration, completion: @escaping (String?) -> Void)
   ```

| **Parameter** | **Description**                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| configuration | A `UADSTokenConfiguration` object that specifies the ad format, mediation info, and other parameters.      |
| completion    | A completion block that is called with the token if it's successfully fetched, or null if an error occurs. |

### Static variables

#### IsInitialized

A boolean property that determines if the Unity Ads SDK is initialized successfully.

1. **Swift**

   ```swift
   @objc public static func isInitialized() -> Bool
   ```

**Returns**: If `true`, Unity Ads has been successfully initialized.

#### getVersion

A string property that determines the current Unity Ads SDK version in use.

1. **Swift**

   ```swift
   public static func getVersion() -> String
   ```

**Returns**: The current installed version of Unity Ads SDK.

#### userIdentifier

Sets a unique ID for each user of your app.

1. **Swift**

   ```swift
   public static var userIdentifier: String
   ```

### Privacy

#### setUserConsent()

Displays the user's opt-in choices for personalized ads.

1. **Swift**

   ```swift
   public static func setUserConsent(_ consentGranted: Bool)
   ```

#### setUserOptOut()

Offers users the option to opt out of data collection and personalized ads.

1. **Swift**

   ```swift
   public static func setUserOptOut(_ optOut: Bool)
   ```

#### setNonBehavioral()

Enables the display of contextual (non-personalized) ads.

1. **Swift**

   ```swift
   public static func setNonBehavioral(_ nonBehavioral: Bool)
   ```

### UnityAdsInitializationDelegate

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use a completion block with [`UnityAds.initialize(_:completion:)`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#unityads) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsInitializationDelegate` was the previous delegate protocol for SDK initialization callbacks.

### UnityAdsLoadDelegate

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use a completion block with [`UADSInterstitialAd.load(_:completion:)`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsinterstitialad) or [`UADSRewardedAd.load(_:completion:)`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsrewardedad) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsLoadDelegate` was the previous delegate protocol for ad loading callbacks.

### UnityAdsShowDelegate

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSInterstitialShowDelegate`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsinterstitialshowdelegate) or [`UADSRewardedShowDelegate`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsrewardedshowdelegate) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsShowDelegate` was the previous delegate protocol for ad show callbacks.

## Enums

### UADSAdFormat

Defines the different types of ad formats supported by Unity Ads.

1. **Swift**

   ```swift
   public enum UADSAdFormat: Int {
       case unspecified = 0, interstitial, rewarded, banner
   }
   ```

| **Parameter** | **Description**                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| unspecified   | No specified ad format.                                                                                   |
| interstitial  | Full-screen ads shown at natural pauses in the app.                                                       |
| rewarded      | Ads that grant users a reward after completion.                                                           |
| banner        | Rectangular ads displayed within the app's layout, typically anchored to the top or bottom of the screen. |

### UnityAdsAdFormat

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use [`UADSAdFormat`](/ads-ios/4.19.0/sdk-integration/api/ios-api-swift.md#uadsadformat) instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsAdFormat` was the previous enum for ad format types.

### UADSLogLevel

Defines the logging levels for Unity Ads.

1. **Swift**

   ```swift
   public enum UADSLogLevel: Int {
       case disabled, error, info, debug
   }
   ```

| **Parameter** | **Description**                                                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| disabled      | No logs output.                                                                                                                              |
| error         | Logs only critical errors and failures in init/load/show operations.                                                                         |
| info          | Logs key operational events (such as initialization started/completed, load started/completed, show started/finished, and token generation). |
| debug         | Logs all info plus detailed internal operations like network requests and internal errors.                                                   |

### UADSShowFinishState

Represents the finish state of an ad after it has been shown.

1. **Swift**

   ```swift
   public enum UADSShowFinishState: Int {
       case skipped = 0, completed
   }
   ```

| **Parameter** | **Description**                                       |
| ------------- | ----------------------------------------------------- |
| skipped       | The user closed or skipped the ad before it finished. |
| completed     | The ad played until the end.                          |

## Protocols

### UADSBannerAdDelegate

1. **Swift**

   ```swift
   public protocol UADSBannerAdDelegate: NSObjectProtocol {
       func bannerImpression(_ banner: UADSBannerAd)
       func bannerDidClick(_ banner: UADSBannerAd)
       func bannerDidFailShow(_ banner: UADSBannerAd, error: UnityAdsError)
   }
   ```

| **Method**                    | **Description**                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `bannerImpression(_:)`        | Called when a banner ad is successfully displayed (impression recorded).               |
| `bannerDidClick(_:)`          | Called when the user clicks the banner ad.                                             |
| `bannerDidFailShow(_:error:)` | Called if the banner fails to display, with an `UnityAdsError` explaining the failure. |

### UADSInterstitialShowDelegate

1. **Swift**

   ```swift
   public protocol UADSInterstitialShowDelegate: NSObjectProtocol {
       func showDidStart(_ unityAd: UADSInterstitialAd)
       func showDidClick(_ unityAd: UADSInterstitialAd)
       func showDidComplete(_ unityAd: UADSInterstitialAd, with state: UADSShowFinishState)
       func showDidFailed(_ unityAd: UADSInterstitialAd, error: UnityAdsError)
   }
   ```

| **Method**                 | **Description**                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `showDidStart(_:)`         | Called when the interstitial ad starts showing.                                                   |
| `showDidClick(_:)`         | Called when the interstitial ad is clicked.                                                       |
| `showDidComplete(_:with:)` | Called when the ad finishes showing. Provides a `UADSShowFinishState` (`skipped` or `completed`). |
| `showDidFailed(_:error:)`  | Called if the ad fails to show, with an `UnityAdsError` explaining the failure.                   |

### UADSRewardedShowDelegate

1. **Swift**

   ```swift
   public protocol UADSRewardedShowDelegate: NSObjectProtocol {
       func showDidStart(_ unityAd: UADSRewardedAd)
       func showDidClick(_ unityAd: UADSRewardedAd)
       func showDidComplete(_ unityAd: UADSRewardedAd, with state: UADSShowFinishState)
       func showDidFailed(_ unityAd: UADSRewardedAd, error: UnityAdsError)
       func showDidReceiveReward(_ unityAd: UADSRewardedAd)
   }
   ```

| **Method**                 | **Description**                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| `showDidStart(_:)`         | Called when the rewarded ad starts showing.                                                       |
| `showDidClick(_:)`         | Called when the rewarded ad is clicked.                                                           |
| `showDidComplete(_:with:)` | Called when the ad finishes showing. Provides a `UADSShowFinishState` (`skipped` or `completed`). |
| `showDidFailed(_:error:)`  | Called if the ad fails to show, with an `UnityAdsError` explaining the failure.                   |
| `showDidReceiveReward(_:)` | Called when the user earns the reward from the ad.                                                |

## UnityAdsError

1. **Swift**

   ```swift
   public protocol UnityAdsError {
       var code: Int { get }
       var message: String { get }
   }
   ```

| **Parameter** | **Description**                                                    |
| ------------- | ------------------------------------------------------------------ |
| code          | A numeric error code that identifies the type of Unity Ads error.  |
| message       | An error message that provides additional details about the error. |

### UADSBannerErrorCode

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use the `UnityAdsError` protocol instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UADSBannerErrorCode` was the previous enum for banner-specific error codes.

### UnityAdsInitializationError

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use the `UnityAdsError` protocol instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsInitializationError` was the previous enum for initialization error types.

### UnityAdsLoadError

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use the `UnityAdsError` protocol instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsLoadError` was the previous enum for ad load error types.

### UnityAdsShowError

> **Warning:**
>
> **Deprecated in version 4.19.0. Scheduled for removal in version 5.0.0.**
>
> Use the `UnityAdsError` protocol instead. See [iOS deprecated APIs](/ads-ios/4.19.0/sdk-integration/api/ios-deprecated-apis.md) for migration details.

`UnityAdsShowError` was the previous enum for ad show error types.