Skip to main content

Add a placement

import Tabs from '@theme/Tabs';

import TabItem from '@theme/TabItem';

For Rokt partners, the Rokt SDK for React Native can be used to display overlay placements on top of your app’s content.

Before you begin​

Ensure that the Rokt React Native SDK has been integrated into your application.

Overlay placements​

Import the SDK​

Import the SDK into your application's JavaScript/TypeScript file:

import { Rokt } from "@rokt/react-native-sdk";

Execute the SDK​

Execute the SDK at the desired point by adding the appropriate customer attributes. The Rokt placement will then display after a short delay that is configurable via the Rokt platform.

You can dictate what customer attributes are included in your Rokt integration. More information on available data fields can be found on the attributes page. If you want to integrate more attributes, you can add additional lines of code for each new attribute to the samples below.

Major Version 3​

<Tabs className="unique-tabs" defaultValue="JavaScript" values={[ {label: 'JavaScript', value: 'JavaScript'}, {label: 'TypeScript', value: 'TypeScript'}, ]}>

const attributes = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};

Rokt.execute("RoktExperience", attributes, {}, () =>
  console.log("Placement Loaded")
);
 
const attributes: Record<string, string> = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};

Rokt.execute("RoktExperience", attributes, {}, () =>
  console.log("Placement Loaded");
);

Major Version 4​

<Tabs className="unique-tabs" defaultValue="JavaScript" values={[ {label: 'JavaScript', value: 'JavaScript'}, {label: 'TypeScript', value: 'TypeScript'}, ]}>

const attributes = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};

Rokt.execute("RoktExperience", attributes, {});
 
const attributes: Record<string, string> = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};

Rokt.execute("RoktExperience", attributes, {});
note

The ViewName (“RoktExperience”) can be modified when executing the SDK in multiple locations to display a different experience according to the context of where in the app the SDK is being executed. If modifying the ViewName, work with the Rokt team to ensure matching adjustments are made within the Rokt system.

Embedded placements​

Import the SDK​

Import the Rokt SDK into the JavaScript/TypeScript file:

import { Rokt, RoktEmbeddedView } from "@rokt/react-native-sdk";

Create a placeholder reference​

Create a placeholder reference in your component:

<Tabs className="unique-tabs" defaultValue="JavaScript" values={[ {label: 'JavaScript', value: 'JavaScript'}, {label: 'TypeScript', value: 'TypeScript'}, ]}>

class MyComponent extends React.Component {
  constructor(props) {
    super(props);
    this.placeholder1 = React.createRef();
    ...
  }
}
 
class MyComponent extends React.Component<MyProps, MyState> {
  constructor(props: MyProps) {
    super(props);
    this.placeholder1 = React.createRef();
    ...
  }
}

Add RoktEmbeddedView to your view​

Add RoktEmbeddedView into your component's returned JSX. The Rokt embedded placement will be injected into this placeholder when the execute method is called:

<RoktEmbeddedView
  ref={this.placeholder1}
  placeholderName={"RoktEmbedded1"}
></RoktEmbeddedView>

Execute the Rokt React Native SDK​

Execute the SDK at the desired point by sending the appropriate customer attributes. The Rokt placement then display after a short delay that is configurable via the Rokt platform.

You can dictate what customer attributes are included in your Rokt integration. More information on available data fields can be found on the attributes page. If you want to integrate more attributes, you can add additional lines of code for each new attribute to the samples below.

Major Version 3​

<Tabs className="unique-tabs" defaultValue="JavaScript" values={[ {label: 'JavaScript', value: 'JavaScript'}, {label: 'TypeScript', value: 'TypeScript'}, ]}>

const placeholders = {
  RoktEmbedded1: findNodeHandle(this.placeholder1.current),
};

const attributes = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};
Rokt.execute("RoktEmbeddedExperience", attributes, placeholders, () =>
  console.log("Placement Loaded")
);
 
const placeholders: Record<string, number | null> = {
  RoktEmbedded1: findNodeHandle(this.placeholder1.current),
};

const attributes: Record<string, string> = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};
Rokt.execute("RoktEmbeddedExperience", attributes, placeholders, () =>
  console.log("Placement Loaded");
);

Major Version 4​

<Tabs className="unique-tabs" defaultValue="JavaScript" values={[ {label: 'JavaScript', value: 'JavaScript'}, {label: 'TypeScript', value: 'TypeScript'}, ]}>

const placeholders = {
  RoktEmbedded1: findNodeHandle(this.placeholder1.current),
};

const attributes = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};
Rokt.execute("RoktEmbeddedExperience", attributes, placeholders);
 
const placeholders: Record<string, number | null> = {
  RoktEmbedded1: findNodeHandle(this.placeholder1.current),
};

const attributes: Record<string, string> = {
  email: "j.smith@example.com",
  firstname: "Jenny",
  lastname: "Smith",
  mobile: "(323) 867-5309",
  postcode: "90210",
  country: "US",
};
Rokt.execute("RoktEmbeddedExperience", attributes, placeholders);
note

The ViewName (“RoktEmbeddedExperience”) can be modified when executing the SDK in multiple locations. This configuration allows you to display a different experience according to the context of where in the app the SDK is being executed. If modifying the ViewName, please work with the Rokt team to ensure matching adjustments are made within the Rokt system.

Callbacks​

Major version 3 of the React Native SDK supports a single onLoad callback that is passed into the execute method. Starting from major version 4, the React Native SDK supports all of the native Rokt SDK callbacks. These callbacks can be received in your components by using a NativeEventEmitter. The following explains how to utilise these callbacks in major version 4 of the SDK.

Import the Required Event Modules​

Import the SDK into your application's JavaScript/TypeScript file:

import { RoktEventManager } from '@rokt/react-native-sdk';
import { NativeEventEmitter } from 'react-native';

Create a NativeEventEmitter​

Create a NativeEventEmitter with RoktEventManager as the nativeModule:`

const eventManagerEmitter = new NativeEventEmitter(RoktEventManager);

If using class components, you can create this outside of your class.

Add a listener to the "RoktEvents" emitter​

From version 4.3.0 "RoktEvents" channel can be subscribed to receive all the events from the SDK.
Add a listener to the emitter with eventType "RoktEvents" and perform actions depending on the callback type:

eventManagerEmitter.addListener('RoktEvents', (data) => {
  switch (data.event) {
    case 'ShowLoadingIndicator':
      console.log(`Event ${data.viewName}`);
      break;
    case 'HideLoadingIndicator':
      console.log(`Event ${data.viewName}`);
      break;
    case 'OfferEngagement':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PositiveEngagement':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'FirstPositiveEngagement':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PositiveEngagement':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PlacementInteractive':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PlacementReady':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PlacementClosed':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PlacementCompleted':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'PlacementFailure':
      console.log(`Event ${data.viewName} ${data.placementId}`);
      break;
    case 'OpenUrl':
      console.log(`Event ${data.viewName} ${data.placementId} ${data.url}`);
    default:
      // default
      break;
  }
});

Event objects​

EventDescriptionOther properties
ShowLoadingIndicatorTriggered before the SDK calls the Rokt backendviewName: String
HideLoadingIndicatorTriggered when the SDK receives a success or failure from the Rokt backendviewName: String
OfferEngagementTriggered when the user engages with the offerviewName: String, placementId: String
PositiveEngagementTriggered when the user positively engages with the offerviewName: String, placementId: String
FirstPositiveEngagementTriggered when the user positively engages with the offer for the first timeviewName: String, placementId: String
PlacementInteractiveTriggered when a placement has been rendered and is interactableviewName: String, placementId: String
PlacementReadyTriggered when a placement is ready to display but has not rendered content yetviewName: String, placementId: String
PlacementClosedTriggered when a placement is closed by the userviewName: String, placementId: 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		viewName: String, placementId: String
PlacementFailureTriggered when a placement could not be displayed due to some failure or when no placements are available to showviewName: String, placementId: String (optional)
OpenUrlTriggered when the user presses a URL that is configured to be sent to the partner appviewName: String, placementId: String, url: String

Add a listener to the "RoktCallback" emitter​

Add a listener to the emitter with eventType "RoktCallback" and perform actions depending on the callback type:

eventManagerEmitter.addListener(
  "RoktCallback",
  (event) => {
    switch (event.callbackValue) {
      case "onLoad":
        // onLoad
      case "onUnLoad":
        // onUnLoad
      case "onShouldShowLoadingIndicator":
        // onShouldShowLoadingIndicator
      case "onShouldHideLoadingIndicator":
        // onShouldHideLoadingIndicator
      default:
        // default
    }
  }
)

If using class components, you can do add the listener in componentDidMount, and remove the listener in componentWillUnmount like so:

eventManagerEmitter.removeAllListeners("RoktCallback");`

Callback types​

onLoad​

The onLoad callback will be called when the placement becomes loaded and interactive.

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.

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.

onUnLoad​

The onUnLoad callback will be called when the SDK closes the placement. It will also be triggered if the execute call fails.

Was this article helpful?