Integration Documentation for Netzyn Ad SDK

Introduction

This document provides instructions for integrating and using the Netzyn Ad SDK in iOS applications. The intended audience is development partners looking to offer trials of mobile applications.

Netzyn Ad SDK is a software development kit designed to enable iOS applications to access virtualized applications running in the cloud for pre-defined periods of time, with the intent to encourage users to install the application should they wish to use it in the future.

Features

The Netzyn Ad SDK provides the following main features:

Accessing virtualized applications from the cloud
Listening for a response from the application
Launching ads via URL

Getting Started

System Requirements

Xcode 16 or later
iOS 17.0 or later

Installation

Please contact support@netzyn.com and we can provide a download for the iOS NZ Ad SDK.

Multiple sample projects demonstrating use of the SDK is also available upon request.

Unzip the SDK, NetzynAds.xcframework.zip to a location inside the project folder.
Drag and drop the NetzynAds.xcframework folder into the lefthand pane in Xcode.
From your application's applicationDidFinishLaunching function, call netzynInitialize to produce an AdSDK instance.
Optionally use openURL and/or continueUserActivity to support URL behaviors.
Otherwise, use the AdSDK instance, and appList to get the list of available remote apps, and runAd to run the app and retrieve an Outcome
Use the Outcome and SKAdNetwork as desired to monitor ad campaigns.

When referencing sample projects, steps 2-6 may be done for you and can be used as a reference.

API Reference

This section documents the API for the Ad SDK. This documentation is also available from within Xcode in a project using the SDK.

Functions

`netzynInitialize`

func netzynInitialize(userID: String, partnerID: String, adConfiguration: AdConfiguration) async -> AdSDK

Initialize the SDK.

This function must be called before other SDK functions.

This asynchronous function must be called from asynchronous context, for example by enclosing it within a Task.

Parameters

userID: Pass a user identifier, if available. You may use identifierForVendor or any other user-specific identifier. Hash this parameter if desired for privacy.
partnerID: A constant identifier for your application. Contact Netzyn support for more information on obtaining this ID.
adConfiguration: An AdConfiguration.

This function returns an opaque type that can be used for other SDK functions.

Example

Task {
   do {
       netzynInitialize(userId:String(describing: UIDevice.current.identifierForVendor), partnerID: "example")
   }
   catch {
       print("\(error)")
   }
}

Correct usage

The function can only be called once. Calling it a second time will trap. The simplest solution is to call it from applicationDidFinishLaunching. For alternatives, see the section on just-in-time initialization below.
The function must be called, and finish (e.g. await) before other SDK functions, such as runAd can be performed.

Just-in-time initialization

A more robust pattern to integrate 3rd-party SDKs is to initialize them just-in-time, upon first use. While this function is lightweight, every bit of optimization to your application launch helps.

Here is a robust example that uses the just-in-time initialization pattern:

/**
 We use a global variable to track whether the SDK has been initialized.

 For global mutable state, the use of a [global actor](https://developer.apple.com/documentation/swift/globalactor) is recommended.  Here we choose the [main actor](https://developer.apple.com/documentation/swift/mainactor).  In this example
 we will show the ad in response to a button press which is dispatched onto the main actor.
 */
@MainActor var initialized = false

class ViewController: UIViewController {
   @IBAction private func tappedShowAd() {
       let appInfo = AppInfo(name: "My Remote App", icon: UIImage(named: "AppIcon")!, netzynAppID: "example", appStoreID: 364709193)
       Task {
           /* Initialize the SDK if needed. */
           if !initialized {
               initialized = true
               await netzynInitialize(userID: "example", partnerID: "example")
           }
           //at this point, the SDK has been initialized.

           try await netzynRunAd(viewController: self, appInfo: appInfo, initialDuration: 30, subsequentDuration: 0, orientation: .all, showsWelcome: true, impression: SKAdImpression())
       }
   }
}

Types

`AdSDK`

The main SDK type.

To construct this type, use netzynInitialize.

struct AdSDK { ... }

`appList`

Gets the list of apps.

Returns the list of apps that can be run as ads.

func appList() async throws -> AppList

Throws

This makes a call to a remote server and may fail if network conditions are unavailable.

`openURL`

Call this function to implement the optional URL-scheme support.

func openURL(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>, urlScheme: String?, universalLinkHost: URL) async throws -> RunResult?

The Netzyn Ads SDK supports URL launching in two ways:

Using a custom URL scheme
Using a universal link

Custom URL schemes

To create a custom URL scheme, register the scheme as described in Apple's documentation. You may register any custom URL scheme.

After registering the scheme, call openURL from your scene delegate's scene(_:openURLContexts:) function.

When using a custom app scheme, use the following format: scheme://?app=id where:

scheme is the custom scheme you registered
id is the id of the app to run. This must match one of a list of Netzyn-supported apps. If the app key is omitted, any app may be chosen.

Universal links

See the documentation at continueUserActivity(_:userActivity:)

returns: nil if we return without error due to the URL scheme not matching the passed value.
throws: various errors due to network connectivity

`continueUserActivity(_:userActivity:)`

Opens a universal link.

First, serve the well-known file as described in Apple documentation. For example, compare with the file served at drew.nz-naas.com/.well-known/apple-app-site-association.

After serving the correct file, add the associated domain to your app. In the example app we use the value applinks:drew.nz-naas.com.

Finally, call this function from scene(_:continue:)

`AdConfiguration`

Configuration type for the Netzyn Ad SDK. This type may be extended as configuration options are added.

`init`

init()

Creates the configuration type.

`prefersMetalRenderer`

var prefersMetalRenderer: Bool = true

Controls whether to use the Metal renderer of the OpenGL renderer. The Metal renderer is the default.

The Metal renderer is the preferred renderer. In the future, the OpenGL renderer will be removed.

This property is deprecated.

`AppList`

The list of apps that can be run as ads.

Returned by AdSDK.appList.

struct AppList { .. }

`apps`

The array of Apps

let apps: [App]

App

struct App { .. }

A remote app that can be run as an ad.

`icon`

Loads the app icon suitable for display in UI.

public func icon() async throws -> UIImage

Throws

This function performs a network request and may fail.

`info`

Returns the Info for this App.

public func info() async throws -> Info

Throws

This function performs a network request and may fail.

`App.Info`

Type necessary to launch the app.

struct Info { ... }

runAd

Run the remote app as an advertisement for UIKit. For the equivalent SwiftUI API, see AdView.

@MainActor func runAd(viewController: UIViewController, showsWelcome: Bool,  impression: SKAdImpression?, loadProductParameters: [String:Any], initialDuration:TimeInterval? = nil, subsequentDuration: TimeInterval? = nil) async throws -> RunResult

viewController: The remote app will be presented onto this viewcontroller using present(animated:).
initialDuration The duration to run the app. This is optional; by default a value specified server-side is used.
subsequentDuration: An additional time to run the app. If this is 0, no additional time is permitted. This is optional; by default a value specified server-side is used.
showsWelcome: If true, a welcome screen will be shown before starting the app. If false, the app will be launched immediately.
impression: The SKAdImpression. If provided, startImpression and endImpression will be called at appropriate times. On iOS 16 and later, StoreKit will receive the impression and can provide attribution.
loadProductParameters: The parameters that will be passed to loadProduct, if any. The App Store ID will be inserted by the implementation. On iOS 15 and earlier, attribution information must be included the product parameters to be correctly attributed in StoreKit.

Throws

Errors indicate some failure to run or complete the impression. For example, this could be impacted by network connectivity.

The netzynInitialize function must be called first.

`orientation`

Interface orientation to use.

let orientation: Orientation

`initialDuration`

The initial duration to run the ad.

let initialDuration: TimeInterval

`subsequentDuration`

The subsequent duration to run the ad.

let subsequentDuration: TimeInterval

`appStoreID`

The app store ID.

let appStoreID: Int

`stars`

let stars: Double

`downloads`

let downloads: String

`apptype`

let apptype: String

`company`

let company: String

`reviews`

let reviews: String

`originalInfo`

The original, opaque data type as returned from the server.

This type is not recommended for use directly, but may be useful if there are someday server keys that are unsupported via the client API.

let originalInfo: Data

`originalInfoString`

The original opaque data type decoded into a String. This type is not recommended for use directly, but may be useful if there are someday server keys that are unsupported via the client API.

var originalInfoString: String?

returns: nil if the server returned a response that cannot be coerced to a string.

`name`

App display name.

var name: String

`Orientation`

enum Orientation { .. }

Describes which orientations should be supported for the remote app.

`landscape`

All landscape orientations will be supported.

`portrait`

All portrait orientations will be supported.

`all`

All orientations will be supported

On iPhone X and other devices following the X design language, portrait upsidedown is not supported. This is an OS limitation.

`Outcome`

Describes the outcome of an ad impression.

enum Outcome { .. }

This provides the user's disposition towards the ad as it relates to the impression itself. For example, did the user take actions during the impression toward the installation of the app.

To find out if the user completed the install and launched the app, you must use SKAdnetwork.

Stability

This enum is non-frozen and graceful handling of unknown cases is recommended for forward-compatibility.

`exited`

The user interactively exited the ad.

`tappedInstall`

The user tapped install. To find out if the user completed the install and launched the app, you must use SKAdnetwork.

If this behavior occurs at any time during the flow, .tappedInstall will be returned, even if the user subsequently exits or declines.

`declined`

The user expressed their intent to decline to install the app.

RunResult

Indicates the result of a call to runAd.

struct RunResult { .. }

`outcome`

The outcome of the ad impression.

let outcome: Outcome

`durationRan`

let durationRan: TimeInterval

The duration the app ran.

This reports the duration of the remote app session.

`cloudAppId`

let cloudappId: String

The cloud app ID of the application run.

This can be correlated with the Netzyn cloud for diagnostic or reporting purposes.

`AdView`

A SwiftUI view to display an ad.

This is the SwiftUI equivalent to runAd.

`init`

public init(app: App.Info, icon: UIImage, showsWelcome: Bool, impression: SKAdImpression?, loadProductParameters: [String : Any], initialDuration: TimeInterval? = nil, subsequentDuration: TimeInterval? = nil)

`app`

An App.Info instance. See App.info().

`icon`

The icon. See App.icon().

`showsWelcome`

If true, a welcome screen will be shown before starting the app. If false, the app will be launched immediately.

`impression`

The SKAdImpression. If provided, startImpression and endImpression will be called at appropriate times. On iOS 16 and later, StoreKit will receive the impression and can provide attribution.

`loadProductParameters`

The parameters that will be passed to https://developer.apple.com/documentation/storekit/skstoreproductviewcontroller/3951378-loadproduct , if any. The App Store ID will be inserted by the implementation. On iOS 15 and earlier, attribution information must be included the product parameters to be correctly attributed in StoreKit.

`initialDuration`

The duration to run the app. This is optional; by default a value specified server-side is used.

`subsequentDuration`

An additional time to run the app. If this is 0, no additional time is permitted. This is optional; by default a value specified server-side is used.

The netzynInitialize function must be called first.

Creates the AdView from the specified App.Info.

The Ad will run automatically when presented into the view hierarchy.

Example usage

     //recommended presentation
     view.fullScreenCover(item: $presentedModel, content: { model in
         AdView(app: model.info!, icon: model.icon!, showsWelcome: true, impression: nil, loadProductParameters: [:])
            //handle results
             .onDismiss({ result in
                 print("\(result)")
                 presentedModel = nil
             })
            //fullscreen
             .ignoresSafeArea()
            //customize fullScreenCover appearance (by default, it's white)
             .presentationBackground(.black.opacity(0.5))
     })

Lifecycle

The ad will take time to load. During this time, it enters a loading state.

At the completion of the ad, the onDismiss(_:) callback will run, and the ad will disappear. At this point, the AdView will be functionally equivalent to an EmptyView.

`onDismiss`

Run the attached block to dismiss the view.

func onDismiss(_ perform: @escaping (Result<RunResult,Error>) -> Void) -> Self

`perform`

The block to run when the view is dismissed. This block will be called with the result of the ad run, or with an error if presentation failed.

Callers can use this to dismiss the view's presentation, for example.