Get started

A newer version of this documentation is available. Switch to the latest version docs.

This guide walks you through the process of adding the Contentsquare SDKs to your React Native application. The Contentsquare Bridge for React Native is a bridge between the Contentsquare SDKs for iOS and Android, and your React Native JavaScript code. It allows for the use of our solution both in native and JavaScript parts of your app. The Contentsquare functionality is provided through an NPM package including only the bridge and dependencies to specific versions of the SDKs. Check the compatibility section for more information about these dependencies, and the minimum React Native version compatible for each version of the bridge.

Note that our Bridge is fully compatible with TypeScript, and includes a .d.ts file in order to get typings within your TypeScript React Native projects when adding the Contentsquare Bridge.

Open up a terminal window and navigate to the folder where your application is stored. First, find the latest version of the bridge compatible with your version of React Native using our compatibility table. Then, install the bridge as follows, specifying the exact version you want to install if needed:

Terminal window
npm install @contentsquare/react-native-bridge
cd ios && pod install

As React Native projects are Objective-C projects for iOS, and our iOS SDK is written in Swift, you will have to embed the Swift standard libraries to your project. To do so, go to the Build Settings of your project’s target, and set the Build Option Embedded Content Contains Swift Code to YES.

Also, you will have to make sure that your CocoaPods version is 1.10.0 or up (pod --version). If it is not, do [sudo] gem install cocoapods. Why? CocoaPods is the tool that we use in order to link our SDK and our bridge for iOS on React Native, and having a lower version will make the linking of the both impossible, as the SDK is now embedded in an XCFramework, which were only supported by CocoaPods in late 2020.

How to import the bridge in your JavaScript code

Section titled How to import the bridge in your JavaScript code

The Contentsquare module is our main module, as well as the default export of our bridge. The Currency module is only used to send Transactions, and contains all supported currencies (see section Track Transactions).

import Contentsquare, { Currency } from '@contentsquare/react-native-bridge';

Important note about React Native apps with native code

Section titled Important note about React Native apps with native code

Depending on if you created your app as a React Native first app, or if you gradually added some React Native code to your Native first app, you might be using some non JavaScript elements in your app, as well as a mix of native screens and JavaScript screens. If that is the case, it is your responsibility to track all of the screens, either by calling our native SDKs directly in the first case, or the bridge in the second. The same remark applies for other functionalities of the SDK - for example, you might need to send a Transaction Event via the native SDK or via the bridge, depending on the technology used to create your buying page.

Have a look at the Android and iOS SDKs to find out how to call them in native parts of your app.

Also, note that we specifically cover the use of the JavaScript bridge in this documentation. You should never call the Bridge’s NativeModule directly yourself. If for any reason you do so, know that we cannot certify that your implementation will work as expected. Only call our SDKs through the JavaScript Contentsquare module we provide in you JavaScript code (as explained in this document), or directly in your native code.

You do not need to do anything to start the SDK. Now that the SDK is a dependency of your app, it will autostart itself when your application starts.

If you prefer to control when the SDK starts, you can disable the autostart feature and programmatically start the SDK when needed.

You need to edit the Info.plist, usually located in ios/{project_name}/, add the following key:

Info.plist
<dict>
...
<key>CSDisableAutostart</key>
<true/>
...
</dict>

Disabling autostart on Android

Section titled Disabling autostart on Android

You need to edit the AndroidManifest.xml, usually located in android/app/src/main/, add the following flag:

AndroidManifest.xml
<application>
...
<meta-data
android:name="com.contentsquare.android.autostart"
android:value="false"
/>
...
</application>

Programmatically start the SDK

Section titled Programmatically start the SDK

Then, you can start the Contentsquare SDK by calling the start() method of the Contentsquare class. This function should be called as early as possible in the app process. Call this function in the useEffect of your App element:

const App = (): JSX.Element => {
...
useEffect(() => {
Contentsquare.start()
...
});
...
}

Note about using Contentsquare along with Expo

Section titled Note about using Contentsquare along with Expo

To use the SDK on an Expo app, you need to have an Expo project with EAS (Expo Application Services). The SDK compatibility with Expo projects requires the extra steps described below.

Add the plugin and your Contentsquare bundle identifier to your app configuration file:

app.json
{
"expo": {
...,
"ios": {
"bundleIdentifier": "com.cs.expo.app", // replace with your bundle id
...
},
"android": {
"package": "com.cs.expo.app", // replace with your bundle id
...
},
"plugins": [
"@contentsquare/react-native-bridge",
],
}
}

To run your Expo app with the Contentsquare SDK, you can’t use Expo Go since it needs native files and features. To run your app, use expo run:ios or expo run:android.
Or, you can replace the scripts to your app in your project’s package.json:

package.json
"scripts": {
...
"android": "expo run:android",
"ios": "expo run:ios",
},

Look at the native SDK docs for validation on each platform.

📚 Validate Android SDK integration
📚 Validate iOS SDK integration

For best implementation practices of our library, explore the Contentsquare for React Native sample app.