ArleneSession

public protocol ArleneSession

The Arlene session allows developers to make adRequests and desplay ads within an ARKit sceneview. The Arlene Session will follow the lifecycle of the active ARSCNView

  • 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 APP_KEY and setup the Arlene Ad serving session.

    import Arlene
    
    class ViewController: UIViewController, ARSCNViewDelegate {
        var sv: ARSCNView!
        lazy var session = Arlene.create(withSceneView: sv)
    
        override func viewDidLoad() {
            super.viewDidLoad()
            sv = ARSCNView() // instantiate scene view
            self.view.insertSubview(sv, at: 0) // add sceneView as a subview
    
            // initialize the ArleneSession
            session.initialise { [weak self] (result, error) in
                if let error = error {
                    // failed to initialize
                    print ("Failed to initialise Arlene: \(error)")
                 } else {
                    // successfull initialization
                 }
            }
         // ...
        }
     // ...
    }
    

    Warning

    You must call Arlene.setKey before this function or you will crash

    Declaration

    Swift

    func initialise(_ completion: @escaping ((Bool, Error?) -> Void))

    Parameters

    completion

    Called when initialisation is complete.

  • Check if the current Arlene session is active

    let sessionSatus = session.getIsSessionActive()
    

    Declaration

    Swift

    func getIsSessionActive() -> Bool
  • The ArleneSession hook within the render loop. The render method allows Arlene to calculate visibility and other related metrics within the ARSCNView.

    func renderer(_ renderer: SCNSceneRenderer, willRenderScene scene: SCNScene, atTime time: TimeInterval) {
       session.render() // must call Arlene during render
       // ..
    }
    

    Note

    render is the second of two methods required to show an ad; showAdNode is the other

    Declaration

    Swift

    func render()
  • In order to show an advertisment within your app, you must first make an ad request from the Arlene Ad Server. To make your request, use the fetchPlacement(withID placementID: '<PLACEMENT_ID>') method, passing in the placementID that is obtained through Arlene Publisher Dashboard. The server will return the appropriate date describing the ad, storing it internally, it will also fetch any required static server assets associated with the ad placement.

    session.fetchPlacement(withID: '<PLACEMENT_ID>', { [weak self] (result, error) in
        if let error = error {
            print ("Failed to initialise Arlene: \(error)")
        } else if result == FetchResult.success
        {
    
            // advertisement is ready to be shown
        } else {
            print (\(result))
        }
    })
    

    Warning

    You must call initialize a session before you can make an ad request

    Declaration

    Swift

    func fetchPlacement(withID placementID: String, _ completion: @escaping ((String, ArleneFetchResult, Error?) -> Void))

    Parameters

    placementID

    The Placement Id provided upon successful creation of a placement within the Arlene Platform

    completion

    Called when data has been fetched from the server and the ad contents have been loaded and it is ready to be shown.

  • After an ad object has been fetched from the server (with fetchPlacement) then it should be added to the scene by calling loadPlacement. Note for convenience, loadPlacement can be called in the completion function of fetchPlacement or immediately after calling fetchPlacement. In the latter case, the load operation will be queued and happen automatically when/if the fetch completes successfully. The function takes three 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. The third completion function will notify you when the load is successful

    session.loadPlacement(withID: '<PLACEMENT_ID>', toNode: nil)
    

    Note

    loadPlacement is the first of two parts required to show an ad; render is the other

    Declaration

    Swift

    func loadPlacement(withID placementID: String, toNode: SCNNode?, autoRemove: Bool, _ completion: @escaping ((String, ArleneLoadResult, Error?) -> Void))

    Parameters

    placementID

    The Placement Id that was used to queue the Ad

    node

    The scene node to use as the parent node for the ad (optional)

    autoRemove

    set wheter you want the ad to remove itself. Defaults to true (optional)

  • After an ad object has been loaded, it can be removed from the scene by calling removePlacement.

    session.removePlacement(withID: '<PLACEMENT_ID>')
    

    Declaration

    Swift

    func removePlacement(withID placementID: String, _ completion: @escaping ((String) -> Void))
  • Get the visibility state of the ad placement. Returns true if the 3D model is within the Scene’s camera view.

    let isRendered = session.isPlacementRendered(withID: '<PLACEMENT_ID>')
    

    Declaration

    Swift

    func isPlacementRendered(withID placementID: String) -> Bool
  • Toggle development mode. When enabled the backend will always serve an ad with placholder creative

    session.developmentMode = true
    

    Note

    Deaults to false.

    Warning

    This is only meant for development and testing purposes, this is not meant to be used in production

    Declaration

    Swift

    var developmentMode: Bool? { get set }