Skip to main content

Add a placement

Before you begin​

Ensure that the Rokt iOS SDK has already been integrated into your application following the steps listed here.

Overlay placements​

Execute the Rokt iOS SDK in your desired ViewController and add all appropriate customer attributes. The example code below uses ViewDidLoad to display a Rokt overlay placement.

The SDK provides optional callback events for when the view loads and unloads.

import Rokt_Widget

class OrderConfirmationViewController: UIViewController {
    
    // call this function when the placement needs to be shown
    func showWidget() {
        let attributes = ["email": "j.smith@example.com",
                "firstname": "Jenny",
                "lastname": "Smith",
                "mobile": "(555)867-5309",
                "postcode": "90210",
                "country": "US"]

        Rokt.execute(viewName: "RoktExperience", attributes: attributes, onLoad: {
            // Optional callback for when the Rokt placement loads
        }, onUnLoad: {
            // Optional callback for when the Rokt placement unloads
        }, onShouldShowLoadingIndicator: {
            // Optional callback to show a loading indicator
        }, onShouldHideLoadingIndicator: {
            // Optional callback to hide a loading indicator
        })
    }
}

Optional functions​

FunctionPurpose
Rokt.close()Used to auto-close overlay placements.

Embedded placements​

Modify your Storyboard​

If you are using SwiftUI, please see the instructions in the SwiftUI table below. If you are not using SwiftUI, please use the following instructions.

In your Storyboard, add a view and put it in your ViewController:

ViewController

On the custom class, set RoktEmbeddedView as the view's class. Then define top, leading, and trailing constraints to match the place that the embedded placement will be shown. For height, we recommend adding a height constraint of zero.

RoktEmbeddedView can only modify the its own height according to the content of the placement. There is a callback in the execute method to notify when the height has changed and return the new height.

The image below illustrates the easiest way to define RoktEmbeddedView using auto layout.

  1. Place RoktEmbeddedView as the Class of view and Rokt_Widget as Module.

  2. Define the top constraints.

  3. Define the leading constraints.

  4. Define the trailing constraints.

  5. Choose height and width constraints.

  6. Set the height constraint.

  7. Add constraints to view.

RoktEmbeddedView

note

The RoktEmbeddedView can also be created in code and included in the layout dynamically.

Execute the Rokt SDK​

Execute the Rokt SDK for iOS in your desired ViewController and add all appropriate customer attributes. The example code below uses ViewDidLoad to launch the placement.

The SDK provides optional callback events for when the view loads and unloads.

import Rokt_Widget
class OrderConfirmationViewController: UIViewController {

   // linked to RoktEmbeddedView created in step 5 or it could be created programmatically
    @IBOutlet weak var roktEmbeddedView: RoktEmbeddedView!

    ...

    // call this function when placement needs to be shown
    func showWidget() {
        let attributes = ["email": "j.smith@example.com",
                "firstname": "Jenny",
                "lastname": "Smith",
                "mobile": "(555)867-5309",
                "postcode": "90210",
                "country": "US"]

       let placements: [String : RoktEmbeddedView] = ["RoktEmbedded1": roktEmbeddedView]

        Rokt.execute(viewName: "RoktEmbeddedExperience", attributes: attributes, placements: placements, onLoad: {
            // Optional callback for when the Rokt placement loads
        }, onUnLoad: {
            // Optional callback for when the Rokt placement unloads
        }, onShouldShowLoadingIndicator: {
            // Optional callback to show a loading indicator
        }, onShouldHideLoadingIndicator: {
            // Optional callback to hide a loading indicator
        }, onEmbeddedSizeChange: { selectedPlacement, widgetHeight in
            // Optional callback to get selectedPlacement and height required by the placement every time the height of the placement changes
        })
    }
}
note

To update the view name RoktExperience or placement name RoktEmbedded1 with a different value, contact your Rokt account manager to ensure Rokt placements are configured consistently.

SwiftUI Component​

Starting from major version 4 of the Rokt iOS SDK, you can add a Rokt layout by utilizing the RoktLayout component. This removes the need to call Rokt.execute and supports a more modern declarative integration using SwiftUI.

Adding the component​

import SwiftUI
import Rokt_Widget

struct OrderConfirmationSwiftUI: View {
    let attributes: [String: String]
    let pageIdentifier: String
    let location: String
    @State var sdkTriggered = true

    var body: some View {
        VStack(alignment: .leading) {

            RoktLayout(sdkTriggered: $sdkTriggered,
                       viewName: pageIdentifier,
                       locationName: location, // If using an embedded layout
                       attributes: attributes,
                       onLoad: {
                // Optional callback for when the Rokt placement loads
            }, onUnLoad: {
                // Optional callback for when the Rokt placement unloads
            },onShouldShowLoadingIndicator: {
                // Optional callback to show a loading indicator
            }, onShouldHideLoadingIndicator: {
                // Optional callback to hide a loading indicator
            })

        }.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
    }
}

note

You can use the RoktLayout component for both embedded and overlay layouts.

Events​

The SDK provides the events on each page through Rokt.events API. 

Rokt.events(viewName: "viewName") { roktEvent in
    print("Rokt event received \(roktEvent)")
}

Event objects​

EventDescriptionParams
ShowLoadingIndicatorTriggered before the SDK calls the Rokt backend
HideLoadingIndicatorTriggered when the SDK receives a success or failure from the Rokt backend
OfferEngagementTriggered when the user engages with the offerplacementId: String
PositiveEngagementTriggered when the user positively engages with the offerplacementId: String
FirstPositiveEngagementTriggered when the user positively engages with the offer for the first timeplacementId: String, setFulfillmentAttributes: func (attributes: [String: String])
PlacementInteractiveTriggered when a placement has been rendered and is interactableplacementId: String
PlacementReadyTriggered when a placement is ready to display but has not rendered content yetplacementId: String
PlacementClosedTriggered when a placement is closed by the userplacementId: String
PlacementCompletedTriggered when the offer progression reaches the end and no more offers are available to display.
Also triggered when cache is hit but the retrieved placement will not be displayed as it has previously been dismissed		placementId: String
PlacementFailureTriggered when a placement could not be displayed due to some failureplacementId: String (optional)
OpenUrlTriggered when the user presses a URL that is configured to be sent to the partner appplacementId: String, url: String

Callbacks​

The Rokt iOS SDK supports the following callbacks which are passed into execute:

onLoad​

The onLoad callback will be called when the placement becomes loaded and interactive. This callback provides no arguments and does not return any values.

onShouldShowLoadingIndicator​

The onShouldShowLoadingIndicator will be called upon a successful execute call, just before the SDK triggers a call to the Rokt backend. It can be used to display progress views of loading indicators while waiting for the placement to load. It does not require any arguments and does not return any values.

note

The behaviour of this callback has changed between major version 3 and major version 4 of the Rokt iOS SDK. There is no longer a 1 second delay before the callback is executed. If you make use of these callbacks in major version 3 and are upgrading to major version 4, test the behavior to ensure the user experience is not impacted. You can create delay behavior that suits your applications needs if necessary.

onShouldHideLoadingIndicator​

The onShouldHideLoadingIndicator callback will be called when the SDK obtains a success or failure response from the Rokt backend. It can be used to cancel progress views or loading indicators. It does not require any arguments and does not return any values.

onUnload​

The onUnload callback will be called when the SDK closes the placement. It will also be triggered if the execute call fails. It does not require any arguments and does not return any values.

onEmbeddedSizeChange​

The onEmbeddedSizeChange will be called when the height of the selected embedded placement or layout undergoes a change. It includes arguments for the selected placement/layout and the new height, but does not return a value.

Was this article helpful?