Arlene iOS SDK

XR Monetization

Arlene is a monetization platform for XR developers. This SDK allows iOS developers to easily embed 3D adertisements within their ARkit enabled apps.

Installation

Using CocoaPods

Add the following to your Podfile:

pod 'arlene-ios-sdk'

Manually

Download arlene-ios-sdk-xx.xx.zip from Releases.

Quick Start

To get started with the Arlene SDK you need to first register for a publsiher account on Arlene.io/register.

Create an app

Within the Arlene Publisher Dashboard, click the “Create App” button. Enter the app’s iTunes URL to auto-populate the fields, otherwise manually enter the app’s name, icon, bundle identifier, categories, and COPPA compliance. After your app has been created, the confirmation page will display your APP Key. Take note of this key, you will need it to initialize the Arlene SDK.

Create a placement

Within the Arlene Publisher Dashboard, select an app, and click the “Create Placement” button. Select your 3D model. This 3D model will appear in your AR scene, with the designated texture replaced with an advertisement.

Setting the App Key

Upon succesful registration, use the “Create an App” button to create your app within the Arlene platform, then either provide an AppStore URL or manually enter the app’s infromation. Once you have created your app, the appKey will be visible on the confirmation screen. Pass the appKey to the Arlene SDK using .setAppKey().

import Arlene

Arlene.setAppKey('<insert your app key here>')

Note: the appKey can be set within the AppDelegate or within the ViewController, the only requirement is that the appKey is set before calling .initialize()

Implimenting the Arlene Session

Initialize the ArleneSession by first declaring and instantiating a reference for the session using Arlene.create(withSceneView: ) passing in your ARkit SceneView. Next, within your ViewControllers viewDidLoad(), call .initialise. This will validate your appKey and setup the Arlene Ad serving session.

import Arlene

class ViewController: UIViewController, ARSCNViewDelegate {
    var sceneView: ARSCNView!
    lazy var arleneSession = Arlene.create(withSceneView: sceneView)

    override func viewDidLoad() {
        super.viewDidLoad()
        sceneView = ARSCNView() // instantiate scene view
        self.view.insertSubview(sceneView, at: 0) // add sceneView as a subview
        arleneSession.initialise { [weak self] (result, error) in
            if let error = error {
                print ("Failed to initialise Arlene: \(error)")     // failed to initialize
            } else {
                // successfull initialization
            }
        }
        // ...
    }
    // ...
}

Fetching an Ad

In order to show an advertisment within your app, you must first make an ad request from the Arlene Network. To make your request, use the fetchPlacement(withID placementID: '<PLACEMENT_ID>', {<completion block>}) method, passing in the placementID that is obtained through Arlene Publisher Dashboard.

arleneSession.fetchPlacement(withID: placementId, { (placementId, result, error) in
    print("fetchPlacement \(placementId) \(result)")
    if result == .placementDownloadCompleted {
        // once thep placement has finished downloading, it is ready to be loaded
    }
})

Showing an Ad

Once an advertisement has been successfully fetched, it can be made visible by calling loadPlacement(withID: '<PLACEMENT_ID>', toNode: <SCNNode>, autoRemove: Bool, {<completion block>}). The function takes two paramenters, the first being the PLACEMENT_ID for the desired ad to be shown, and the second is optional and allows you to show the 3D advertisement as a child of a give node. If the parameter is left empty, the Arlene SDK will default to using the scene’s root node.

arleneSession.loadPlacement(withID: placementId, toNode: adRoot, autoRemove: true, { (placementId, result, error) in
    print("loadPlacement \(placementId) \(result)")
})

There are two parts to showing an ad. The first (above) allows you to choose when/where to attach the 3D advertisement. The second part is related to the renderig of the model within the render loop.

func renderer(_ renderer: SCNSceneRenderer, updateAtTime time: TimeInterval) {
    arleneSession.render()
    // ..
}

Other Features

Development Mode

During the development and testing phase of your project, set the ArleneSession to developer mode. While developer mode is enabled, the Arlene SDK will to consistantly load a “test” advertisement to ensure that the advertisment is always loaded into the scene.

arleneSession.developmentMode = false

Checking Arlene session state

There Arlene SDK provides a method to check if the current session is active using getIsSessionActive().

arleneSession.getIsSessionActive()