React Native

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.17.0"

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

  pod 'MonterosaSDKCommon', :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, type MonterosaMessageEvent, type MonterosaSdkConfiguration } from '@monterosa-sdk/react-native';

export default function App() {

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

  const config: MonterosaSdkConfiguration = {
    host: '<HOST>',
    projectId: '<PROJECTID>',
  };

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

Please note that when embedding an experience, the experienceUrl field is not required in the configuration and should not be set.

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.

To ensure the token is transmitted correctly, it must be set after the view has been initialized. To achieve this, update the configuration object with the token once the view is fully loaded. The following snippet demonstrates how this can be achieved:

import * as React from 'react';
import { MonterosaSdkExperienceView, type MonterosaSdkConfiguration } from "react-native-monterosa-sdk";

//..

// Initial config without the token
  const [config, setConfig] = React.useState<MonterosaSdkConfiguration>({
    host: '<HOST>',
    projectId: '<PROJECTID>',
  });

  useEffect(() => {
    // Simulate fetching the token
    const fetchToken = async () => {
      // Replace with your emitted token
      const token = "<MY TOKEN>";
      
      // Update the config
      setConfig(prevConfig => ({
        ...prevConfig,
        token: token
      }));
    };

    fetchToken();
  }, []);

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

Update the config with the token once the message didBecomeReady has been received. 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.

Login prompted by Experience

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: MonterosaMessageEvent) => {
  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}
    ...
  />
);

Configure the Experience

The SDK allows for configuration and customisation of the Experience view through adjustable props, aligning with your app's specific needs.

You can read more on this available configuration options here

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

// ...

<MonterosaSdkExperienceView
  style={{ flex: 1 }}
  configuration={{
    host: "https://your-host.com",
    projectId: "your-project-id",
    parameters: {
      source: "mobile_app",
      theme: "dark"
    }
  }}
/>

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: MonterosaMessageEvent) => {
  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

Resizing Embedded Experiences using the React Native SDK

The Monterosa Web SDK supports automatic resizing of embedded content via the autoresizesHeight flag. This ensures that the Experience notifies its parent container (e.g. an iframe or wrapper) whenever its height changes, allowing for a seamless layout with no internal scroll bars or clipped content.

However, this functionality is not currently available in the React Native SDK.

When embedding an Experience inside a MonterosaSdkExperienceView in a React Native app, the container does not automatically adjust its height when the content inside the Experience changes. As a result, developers may observe issues such as:

• Cropped content

• Scrollbars appearing within the WebView

• Extra spacing below or above the Experience

Available Workaround

To support dynamic sizing in React Native, Monterosa offers a custom workaround that can be implemented in the embedded Experience.

This approach involves:

• Adding a ResizeObserver inside the Experience to track changes to the layout (e.g. from user interaction, timers, or content updates)

• Sending a structured message via the SDK’s messaging interface when the size changes

• Listening to that message in the React Native host using the onMessageReceived prop

• Dynamically adjusting the height of the WebView based on the provided dimensions

⚠️ Note: This resizing behaviour is not built into the React Native SDK by default. It requires additional implementation within the Experience itself, and coordinated handling in the host app. If your use case requires this functionality, please consult with your Monterosa contact to determine feasibility and integration requirements.

Additional Parameters

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}
    ...
  />
);