@ccm19/sdk-react-native v1.0.3

CCM19 SDK for React Native

About

The CCM19 Software Development Kit (SDK) for React Native enables seamless integration into mobile applications built with React Native.

Prerequisites

The following minimum requirements are the versions tested during development. Older versions may work, but are not officially supported.

• Android >= 12 (Snow Cone)
• iOS >= 17.4
• Node >= 20
• React Native >= 0.75
• CCM19 >= 2025.02.06

Create a React Native project

You can use the React Native Community CLI to create a new React Native project:

npx @react-native-community/cli@latest init YourProjectName

To create a project with a specific React Native version, the --version parameter can be used

npx @react-native-community/cli@latest init YourProjectName --version 0.75.5

Integration

Addressing the issue with autolinking native modules

When React Native autolinks modules, it ignores transient dependencies, which are indirectly required through dependencies of the project. Without these modules explicitly listed in your project's package.json, the compiler can't find them, leading to build failures or unexpected runtime errors. This means your app might crash, or specific functionalities tied to those modules won’t work, making the whole development process a real headache. By explicitly adding these dependencies in your project's package.json, the build process can succeed.

For more information on this, refer to the following links:

• https://github.com/react-native-community/cli/issues/870
• https://github.com/react-native-community/cli/issues/923
• https://github.com/react-native-community/cli/blob/main/docs/autolinking.md

To address this problem, manually edit the package.json of your project and add the following dependencies:

{
  "dependencies": {
    "@react-native-async-storage/async-storage": ">=1.22.3",
    "@react-native-masked-view/masked-view": ">=0.3.2",
    "@react-navigation/native": ">=6.1.16",
    "@react-navigation/native-stack": ">=6.9.25",
    "@react-navigation/stack": ">=6.3.29",
    "react-native-gesture-handler": ">=2.15.0",
    "react-native-localize": ">=3.3.0",
    "react-native-reanimated": ">=3.15.4",
    "react-native-safe-area-context": ">=4.9.0",
    "react-native-screens": ">=3.34.0"
  }
}

It is assumed that the dependencies react and react-native already exist and are therefore not explicitly listed.

Run npm install to install the dependencies.

Add the SDK to your project

To use the SDK, install the @ccm19/sdk-react-native package.

From official npm repository

npm install --save @ccm19/sdk-react-native

Use a local copy

Alternatively, you can install a local copy of the @ccm19/sdk-react-native package like so:

# Does not work, keep reading.
npm install --save ../ccm19-sdk-react-native

In the example above, we expect the SDK to be placed alongside the project directory inside the "ccm19-sdk-react-native" folder – i.e. ../ccm19-sdk-react-native. If you have just cloned the SDK, remember to run npm install.

The problem with this approach is that npm will create a symlink to the module's directory and React Native won't be able to resolve source files.

Fortunately, npm introduced a solution in version 8.8.0 by implementing the --install-links option to install file: dependencies, rather than creating a symlink.

npm install --save --install-links ../ccm19-sdk-react-native

Note that you'll have to use --install-links on subsequent npm calls to preserve the module, or else it will be replaced by a symlink. If that happens, you can reinstall the SDK using these commands:

npm uninstall @ccm19/sdk-react-native
npm install --save --install-links ../ccm19-sdk-react-native

More info: https://docs.npmjs.com/cli/v10/commands/npm-install#install-links

When set file: protocol dependencies will be packed and installed as regular dependencies instead of creating a symlink. This option has no effect on workspaces.

Import the library into your application

To integrate the library into your application, do as follows:

Connect the app to your account

To configure your installation, import the class CCM19 into your main module and call CCM19.configure before your app or ConsentWidget is rendered.

import { CCM19 } from '@ccm19/sdk-react-native';

// […]

CCM19.configure({
  apiKey: 'your-api-key',
  appId: 'your-app-id',
  baseUrl: 'https://cloud.ccm19.de',
});

function App(): React.JSX.Element {
  // […]
}

The following properties are required to connect the app to your account:

• apiKey: string – The API key of the corresponding user account.
• appId: string – The ID of the corresponding (app) project.
• baseUrl: string – The base URL to the CCM19 instance.

Add the consent widget to your app

To add the consent widget to your app, import the ConsentWidget component.

import { ConsentWidget } from '@ccm19/sdk-react-native';

Insert the ConsentWidget component, for example, into your main component.

function App(): React.JSX.Element {
  // […]

  return (
    <SafeAreaView>
      {/* […] */}
      <ConsentWidget />
    </SafeAreaView>
  );
}

If the user has not interacted with the consent widget yet – i.e. there is no consent configuration – the consent widget will open automatically and prompt the user to set up their consent settings.

Reopen the consent widget

You may want to give your users the ability to change or update their consent settings. You can do this by calling CCM19.openConsentWidget.

Example:

function App(): React.JSX.Element {
  // […]

  return (
    <SafeAreaView>
      <ScrollView>
        <View>
          <Section title="Your consent">
            {/* Use API function as event listener */}
            <Button title="Change consent" onPress={CCM19.openConsentWidget} />
          </Section>
        </View>
      </ScrollView>
      {/* Place the ConsentWidget component like before */}
      <ConsentWidget />
    </SafeAreaView>
  );
}

Start Metro, then build and run the app

Run on Android

To start Metro, run the following command in a separate terminal:

npm start

# To reset the cache, use the following command instead
npm start -- --reset-cache

Run the following command to build the app for Android and run it on a connected hardware device or on a running virtual device:

npm run android

Run on iOS

First, you have to update the CocoaPods configuration:

cd ios
pod install

# Switch back to the project's root directory
cd ..

Run the following command to start Metro, build the app and run on an iDevice:

npm run ios