Integrate the Genuin Ad SDK for iOS

Integrate IAB-compliant, tag-driven advertisements into your iOS application using the Genuin Ad SDK.

The SDK enables publishers and brands to seamlessly display interactive advertising experiences within their native applications while maintaining complete control over ad placement, campaign management, and user engagement.

Whether you're embedding a compact banner, a medium rectangle, or a collapsible rich media unit, the SDK provides a lightweight integration that automatically handles ad delivery, rendering, playback, and lifecycle management.

This guide walks through every step, from installing the SDK to displaying your first advertisement and monitoring ad events.

Who Should Use This Guide?

This guide is intended for:

• iOS developers integrating Genuin advertising into mobile applications
• Engineering teams implementing IAB-compliant advertising
• Publishers monetizing applications with managed advertising inventory
• Brands delivering sponsored experiences across their mobile properties

What You'll Learn

By the end of this guide, you'll know how to:

• Install the Genuin Ad SDK using Swift Package Manager
• Configure the required Google Interactive Media Ads dependency
• Initialize the SDK correctly
• Display responsive advertisement units
• Deliver campaigns using Tag IDs
• Observe advertisement lifecycle events
• Handle loading failures gracefully
• Integrate advertisements into both SwiftUI and UIKit applications

Before You Begin

Throughout this guide you'll encounter two placeholder values that should be replaced with credentials from your own Genuin account.

These credentials authenticate your application and determine which advertisements are displayed.

Table of Contents

This guide covers:

1. Requirements
2. What the SDK Provides
3. Install the SDK using Swift Package Manager
4. Install the Google Interactive Media Ads Dependency
5. Link Frameworks to Your Application
6. Configure Your Application
7. Retrieve Your Credentials
8. Initialize the SDK
9. Display Advertisements
10. Advertisement Formats
11. Tag-Based Advertisement Delivery
12. Advertisement Lifecycle Events
13. Error Handling
14. UIKit Integration
15. Application Size
16. Troubleshooting
17. Support

1. Requirements

Before integrating the SDK, verify that your development environment satisfies the following requirements.

2. What the SDK Provides

The SDK is distributed as a single Swift Package containing two primary products.

Once integrated, the SDK provides four ready-to-use SwiftUI advertisement components.

These components automatically manage:

• Advertisement retrieval
• Media playback
• Creative rendering
• Impression tracking
• User interaction
• Lifecycle management

allowing developers to integrate advertising with minimal implementation effort.

3. Install the SDK Using Swift Package Manager

The recommended installation method is Swift Package Manager (SPM).

Step 1: Open Package Manager

Open your project in Xcode.

Navigate to: File → Add Package Dependencies...

Step 2: Add the Genuin Package

Paste the following repository URL:

https://github.com/genuininc/ios_sdk

Configure the dependency rule as: Up to Next Major Version

using the latest available release (for example, 1.0.0).

Click Add Package.

Step 3: Select the SDK Products

When Xcode prompts you to choose package products, select both:

• GenuinSDK
• IABAds

Assign both products to your application target.

Finally, click Add Package.

At this stage, your project includes all Genuin framework components required to initialize the SDK and render advertisement views.

4. Add the Google Interactive Media Ads Dependency

The Genuin Ad SDK is distributed as binary frameworks.

Apple's binary frameworks cannot automatically declare package dependencies.

Because advertisement playback relies on Google Interactive Media Ads (IMA), your application must install the Google IMA framework separately.

If this dependency is missing, the application will crash during launch with an error similar to:

dyld: Library not loaded:
@rpath/GoogleInteractiveMediaAds.framework/...

Install Google IMA

Within Xcode:

Navigate to: File → Add Package Dependencies...

Paste the following package URL:

https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios

Configure the dependency as: Branch → main

Then add the following product to your application target:

• GoogleInteractiveMediaAds

Why This Dependency Is Required

The Google IMA SDK is responsible for:

• Video advertisement playback
• Audio advertisement playback
• Interactive advertisement rendering
• Media controls
• Playback lifecycle

Without this framework, Genuin advertisement components cannot function.

5. Link Frameworks to Your Application

After installation, verify that all required frameworks are linked to your application.

Open your application target.

Navigate to: General → Frameworks, Libraries & Embedded Content

Confirm the following products are listed:

• GenuinSDK
• IABAds
• GoogleInteractiveMediaAds

No additional embedding configuration is necessary.

When using Swift Package Manager, Xcode automatically embeds and signs the frameworks during the build process.

6. Configure Your Application

The SDK supports Apple's App Tracking Transparency (ATT) framework for advertisement measurement and personalized advertising.

To comply with App Store guidelines and enable advertising analytics, your application should request tracking authorization from users.

Add the App Tracking Transparency Usage Description

Add the following entry to your application's Info.plist.

<key>NSUserTrackingUsageDescription</key>
<string>We use your data to show you more relevant ads.</string>

This message is presented when iOS requests tracking permission.

You may customize the text to align with your organization's privacy policy.

Request Tracking Authorization

After the application launches, or at an appropriate point during onboarding - request tracking authorization.

import AppTrackingTransparency
ATTrackingManager.requestTrackingAuthorization { _ in }

Network Configuration

Advertisement assets are delivered securely over HTTPS.

Because Apple's App Transport Security (ATS) allows secure HTTPS connections by default:

• No custom ATS configuration is required.
• NSAllowsArbitraryLoads should not be enabled for standard advertisement delivery.

7. Retrieve Your Credentials

Before initializing the SDK, obtain your application credentials.

You'll need two values.

8. Initialize the SDK & Protect Your API Key

Although the SDK API Key is intended for client-side authentication, it should still be stored securely.

Recommended approaches include:

• Build Settings
• XCConfig files
• Environment-specific configuration
• CI/CD secrets

Avoid committing API keys directly into public source repositories.

Display Your First IAB Advertisement

After initializing the SDK, displaying an advertisement only requires adding one of the provided SwiftUI ad components to your application's view hierarchy.

Each ad component automatically:

• Connects to the Genuin platform
• Retrieves creatives associated with the supplied Tag ID
• Handles media playback
• Tracks impressions and engagement
• Manages the complete ad lifecycle

Simply place the ad view wherever you want advertisements to appear inside your SwiftUI layout.

Invoke Genuin.shared.initialize(...) only once during the application launch sequence. This should occur within the App initializer for SwiftUI or the application(_:didFinishLaunchingWithOptions:) method in UIKit. It is mandatory to include BGIABAds.module to ensure the advertisement components can properly initialize their underlying rendering engine.

import SwiftUI
import GenuinSDK
import IABAds

@main
struct MyApp: App {
    init() {
        Genuin.shared.initialize(
            modules: [BGIABAds.module],   // register the IAB ads module
            apiKey: "YOUR_API_KEY"
        )
    }

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

9. Display an ad

Each ad unit is a standard SwiftUI View. Drop it anywhere in your hierarchy and seed it with a tag ID:

Once rendered, the SDK automatically fetches the creative associated with the supplied Tag ID and displays it without requiring any additional implementation.

import SwiftUI
import IABAds
import Core

struct ContentView: View {
    var body: some View {
        VStack {
            Text("Ad Unit")
                .font(.caption)
                .foregroundStyle(.secondary)

            BGNavigationRoot () {
                IAB300x50AdView(tagID: "<YOUR_TAG_ID>")
            }
        }
        .padding()
    }
}

10. Supported Ad Formats

The SDK currently provides four built-in ad formats optimized for different placement scenarios.

All units expand to the full width of their container and pin to their format's height, so place them in a layout that provides width (e.g. a VStack with padding, a list row, or a fixed‑width column). You don't need to set a frame.

IAB300x100AdView(tagID: "YOUR_TAG_ID")

IAB300x250AdView(tagID: "YOUR_TAG_ID")

IAB300x50AdView(tagID: "YOUR_TAG_ID")

IABCollapsibleAdView(tagID: "YOUR_TAG_ID")

No manual frame calculations are required.

11. Choosing Between Tag IDs and Direct Ad URLs

The SDK supports two methods of supplying advertisement content.

Recommended: Tag ID

For most implementations, advertisements should be loaded using a Tag ID generated from the Genuin platform.

// Resolve a feed from a Genuin ad tag (most common):
IAB300x250AdView(tagID: "YOUR_TAG_ID")

Using Tag IDs allows advertisements to be managed entirely from the Brand Control Center without requiring application updates.

Benefits include:

• Dynamic campaign management
• Remote creative updates
• Audience targeting
• Placement optimization
• Campaign reporting

12. Observe Advertisement Lifecycle Events (BGAdDelegate)

Applications often need to react to advertisement events such as:

• Ad loaded
• Impression started
• Video completed
• User clicked CTA
• Enter full-screen
• Collapse
• Errors

The SDK exposes these events through the BGAdDelegate protocol.

Import both modules:

import IABAds
import _FeedCore

Example delegate implementation:

import IABAds
import _FeedCore
import Core


final class AdTracker: BGAdDelegate {
    /// Ad-unit lifecycle
    func iabAdUnitDidLoad(_ unit: BGAdUnitInfo, mediaCount: Int) {
        print("Ad loaded with \(mediaCount) item(s) for tag \(unit.tagID ?? "—")")
    }
    func iabAdUnitDidReceiveNoAds(_: BGAdUnitInfo) {
        print("No ads available")
    }
    func iabAdUnitDidFailToLoad(_: BGAdUnitInfo, error: BGTagError) {
        print("Ad failed: \(error)")
    }
    // Media lifecycle
    func iabAdMediaDidStart(_: BGMediaInfo) { /* impression started */ }
    func iabAdMediaDidComplete(_: BGMediaInfo) { /* creative finished */ }
    func iabAdAllMediaDidComplete(_: BGAdUnitInfo) { /* whole unit played */ }
    /// User interaction
    func iabAdCTATapped(_: BGMediaInfo, url: URL) {
        print("CTA tapped → \(url)")
    }
    func iabAdWatchTapped(_: BGMediaInfo) { /* opened fullscreen */ }
}

Attach the delegate to any advertisement view.

struct ContentView: View {
    // Keep a strong reference — the delegate is held weakly by the view.
    @State private var tracker = AdTracker()

    var body: some View {
	 BGNavigationRoot {
        	IAB300x250AdView(tagID: "YOUR_TAG_ID", delegate: tracker)
	 }
    }
}

Full callback reference

1. Ad‑unit lifecycle

• iabAdUnitDidStartLoading(_:) — started fetching the feed.
• iabAdUnitDidLoad(_:mediaCount:) — feed resolved to ≥1 renderable item.
• iabAdUnitDidReceiveNoAds(_:) — feed resolved but empty.
• iabAdUnitDidFailToLoad(_:error:) — feed fetch failed (BGTagError).

2. Media lifecycle

• iabAdMediaDidAppear(_:) — an item became the active on‑screen cell.
• iabAdMediaDidStart(_:) — the creative resolved / playback began.
• iabAdMediaDidFailToFill(_:) — an audio item's ad‑slot waterfall produced no fill.
• iabAdMediaDidComplete(_:) — the item's audio/video reached the end.
• iabAdMediaDidChange(from:to:) — the pager moved between items.
• iabAdAllMediaDidComplete(_:) — the last item finished (unit played through once).

3. User interaction

• iabAdMuteStateDidChange(_:isMuted:)
• iabAdWatchTapped(_:) — the "Watch" affordance was tapped.
• iabAdCTATapped(_:url:) — the CTA / advertiser domain was tapped.

4. Presentation & layout

• iabAdDidEnterFullscreen(_:) / iabAdDidExitFullscreen(_:)
• iabAdDidCollapse(_:reason:) (reason is .auto or .user) / iabAdDidExpand(_:)

Payload Objects

The SDK exposes detailed metadata for each advertisement.

BGAdUnitInfo

Contains:

• Unit ID
• Tag ID
• Ad format

BGMediaInfo

Contains:

• Media ID
• Creative type
• Media index
• Total creatives
• Media item
• Audio/Sponsored classification

These payloads enable advanced analytics, reporting, and custom event tracking.

Error Handling

Failures are reported via iabAdUnitDidFailToLoad(_:error:) as an BGTagError:

If an error occurs, the SDK automatically renders an Ad Unavailable placeholder to preserve layout consistency.

14. UIKit Integration

Although the SDK is built using SwiftUI, UIKit applications can integrate it using UIHostingController.

import UIKit
import SwiftUI
import IABAds

let adView = IAB300x250AdView(tagID: "YOUR_TAG_ID")
let hosting = UIHostingController(rootView: adView)

addChild(hosting)
hosting.view.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(hosting.view)
NSLayoutConstraint.activate([
    hosting.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
    hosting.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
    hosting.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
])
hosting.didMove(toParent: self)

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Genuin.shared.initialize(modules: [BGIABAds.module], apiKey: "YOUR_API_KEY")
    return true
}

15. App Size Impact

Integrating the GenuinAds SDK introduces only a modest increase in application size.

16. Troubleshooting

App Crashes on Launch

dyld: Library not loaded:
GoogleInteractiveMediaAds.framework

Cause

The Google Interactive Media Ads package has not been added to your project.

Resolution

Add the Google IMA Swift Package and ensure it is linked to your application target.

"Ad Unavailable" Placeholder Appears

• Confirm you passed BGIABAds.module to initialize(...).
• Confirm your apiKey is correct and non‑empty.
• Confirm the tagID is valid and active in your dashboard.
• Implement iabAdUnitDidFailToLoad(_:error:) to see the precise BGTagError.

adsManagerUnavailable error initialize(...) was called without BGIABAds.module, or it wasn't called before the ad view appeared.

Build error: "no such module 'GenuinSDK' / 'IABAds'" Make sure both products are added to your app target (not just resolved at the project level), and that your deployment target is iOS 16.0+.

Build/resolve error mentioning macOS This package is iOS‑only. Ensure you're building for an iOS destination; remove macOS from your target's supported destinations if present.

17. Support

For additional assistance during integration:

Documentation

Access your organization's Genuin documentation and developer resources.

Dashboard

Retrieve credentials, manage ad tags, and configure placements through the Brand Control Center.

Contact Support

When opening a support request, include:

• Project ID
• SDK Version
• Xcode Version
• iOS Version
• Device Model
• Complete error message
• Returned Error (if applicable)
• Relevant console logs

Providing this information helps the Genuin engineering team diagnose and resolve issues more efficiently.