Embed with React Native SDK

Monterosa / Interaction SDK allows you to embed an Experience in your React Native app.

Getting started

Prerequisites

First of all, you'll need a React Native application into which you'll install the SDK. This guide assumes you have created it using a command similar to the one recommended by React Native's documentation:

npx create-expo-app MyApp

If that is the case, you'll need to generate the iOS and Android projects in order for the SDK to be installed. This can be done with the commands:

npx expo run:ios

and

npx expo run:android

Once this is done, you should have a folder structure that includes an ios and android folders.

Installation

The first step is to install the React Native SDK NPM package. This can be done with the following snippet (making sure to replace the package token provided):

npm config set @monterosa-sdk:registry https://gitlab.com/api/v4/projects/38419920/packages/npm/
npm config set //gitlab.com/api/v4/projects/38419920/packages/npm/:_authToken "<package token>"
npm install @monterosa-sdk/react-native

As a result of this command, your node_modules will include a package called @monterosa-sdk/react-native, which includes:

The Android code necessary to interact with the native Android SDK from React Native
The iOS counterpart to that code
The JavaScript wrapper code

You'll need to update your Android and iOS projects to link to the Android and iOS native SDKs.

Android Setup

In order to setup the Android app, you'll need to install the native SDKs. To do so, enter the following snippet in the android/settings.gradle file:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://gitlab.com/api/v4/projects/38419902/packages/maven"
            credentials(HttpHeaderCredentials) {
                name = 'Deploy-Token'
                // The format of the token should be similar to: 'SC3hJTmsGtEJFpwk-XEU'
                value = '<YOUR TOKEN>'
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
}

Once that is entered, the React Native SDK will be able to obtain the native SDK libraries required for it to operate.

Finally, you'll need to make sure that the minimum Android API level is set to 23, as opposed to the default 21 in the React Native setup. This can be achieved by updating the minSdkVersion value in android/build.gradle:

minSdkVersion = Integer.parseInt(findProperty('android.minSdkVersion') ?: '23')

iOS Setup

Similarly to Android, we need to update the Podfile in ios/Podfile in order to be able to locate the native SDK libraries. This can be achieved by adding the following lines to the target of your app:

target 'MyApp' do
  username = "<YOUR USERNAME>"
  token = "<YOUR TOKEN>"
  version = "0.16.8-RN-RC1"

  url = "https://#{username}:#{token}@gitlab.com/monterosa-sdk/ios.git"

  pod 'MonterosaSDKCommon', :git => url, :tag => version
  pod 'MonterosaSDKConnectKit', :git => url, :tag => version
  pod 'MonterosaSDKCore', :git => url, :tag => version
  pod 'MonterosaSDKLauncherKit', :git => url, :tag => version
  pod 'MonterosaSDKIdentifyKit', :git => url, :tag => version

  use_expo_modules!
  config = use_native_modules!
  ...
end

Note that the pods of the SDK need to be declared BEFORE the calls to use_expo_modules and use_native_modules occur.

Embedding an Experience

Once the installation is resolved, you can embed an Experience by using the next snippet:

import { useRef } from 'react';
import { MonterosaSdkExperienceView } from '@monterosa-sdk/react-native';

export default function App() {

  const onMessageReceived = (e) => {
    console.log('Message received: ', JSON.stringify(e.nativeEvent, null, 2));
  };

  const config = {
    host: 'cdn-dev.monterosa.cloud',
    projectId: '098b5de9-dc67-49db-8357-e532f27acef1',
  };

  return (
    <MonterosaSdkExperienceView
      style={{
        flex: 1
      }}
      onMessageReceived={onMessageReceived}
      configuration={config}
    />
  );
}

Events in the SDK

The SDK offers a onMessageReceived prop where a function can be passed to receive the messages from the native implementations. These messages cover from Messages sent from the Experience, to debug messages.

You can read more on this topic here.

SSO Integration with your IAM provider

Through Identify, Monterosa supports SSO integrations with a suite of IAM providers and has the capacity to create bespoke integrations when needed.

Pre-requisite

Please contact our sales team if you're interested in setting up the integration between your IAM provider, and Identify.

SSO via React Native SDK

Using the React Native SDK, you can pass a token to the MonterosaSdkExperienceView so that it is used to log-in the user within the Experience with a token property in the configuration. This can be achieved with the following snippet:

import { MonterosaSdkExperienceView } from "react-native-monterosa-sdk";

// ...
const config = {
  host: 'cdn-dev.monterosa.cloud',
  projectId: '098b5de9-dc67-49db-8357-e532f27acef1',
  // Replace the token with one emitted by your 
  token: "<MY TOKEN>"
};

return (
  <MonterosaSdkExperienceView
    configuration={config}
    ...
  />
);

The token provided will be later submitted to Identify when attempting to log-in the user.

Additionally, we support a range of Identify Events documented here.

In many cases, Monterosa / Interaction Cloud encourages the sign-up of users to your platform via gated content. This is achieved by sending an event to the application when the user taps on a "Sign up" button in the UI of the Experience.

The following snippet outlines how to intercept the event:

const onMessageReceived = (e) => {
  const ev = e.nativeEvent;
  if (ev.type === "identifyEvent" &&  ev.payload.event === "didRequestLoginByExperience") {
      // The user attempted to sign-up in the Experience, raise a sign up or log in flow
      // for them to access the app.
  }
};

return (
  <MonterosaSdkExperienceView
    onMessageReceived={onMessageReceived}
    ...
  />
);

Sending messages to the Experience

In order to enable a seamless User Experience, it's often necessary to communicate with the Experience to share necessary information with the app. The SDK offers the capacity to send and receive messages following the next snippet:

const viewNode = useRef(0)

const onMessageReceived = (e) => {
  const ev = e.nativeEvent;
  if (ev.type === "experienceMessage") {
      // We received a message
      const { action, payload } = ev.payload;
      
      // Depending on the action, do something. The required metadata is present in the payload.
  }
};

// Action is a string, payload a dictionary
function sendMessageToExperience(action, payload) {
  sendMessage(viewNode, action, payload);
}

// Sample usage -- Notice it depends on the Experience being running, so should be deferred until the Experience is created
sendMessageToExperience("my_action", { my_payload_property: 42 });

return (
  <MonterosaSdkExperienceView
    onMessageReceived={onMessageReceived}
    ref={viewNode}
    ...
  />
);

Sending additional parameters to the Experience

Using the React Native SDK, you can pass additional parameters to the Experience when you create it. To do so, provide a dictionary in the parameter key of the configuration property in the MonterosaSdkExperienceView. This can come in useful for the initial configuration of the Experience, for instance, setting up the language to use:

import { MonterosaSdkExperienceView } from "react-native-monterosa-sdk";

const config = {
  // ...
  parameters: {
    lang: 'en'
  },
  // ...
};

return (
  <MonterosaSdkExperienceView
    configuration={config}
    ...
  />
);

PreviousUse the SDK to communicate with the embedded Experience NextEvents in React Native SDK