@axeptio/react-native-sdk

Axeptio React Native SDK Integration

This repository demonstrates how to implement the Axeptio React Native SDK into your mobile applications to handle user consent for GDPR compliance and other privacy regulations.

The SDK is customizable for both brands and publishers, depending on your use case and requirements.

📑 Table of Contents

• GitHub Access Token Setup
• Setup
  • Installation
  • Android Setup
  • iOS Setup
• Initialize the SDK on App Startup
• ATT (App Tracking Transparency) Integration Note
• Responsibilities: Mobile App vs SDK
• Get Stored Consents
• Show Consent Popup on Demand
• Sharing Consents with Other Web Views
• Clear Users Consent Choices
• Events

GitHub Access Token Setup

When setting up your project or accessing certain GitHub services, you may be prompted to create a GitHub Access Token. Please note that generating this token requires:

• A valid GitHub account.
• Two-factor authentication (2FA) enabled.

To avoid authentication issues during setup, we recommend reviewing the official GitHub Access Token Documentation or detailed instructions on how to create your token and ensure 2FA is properly configured. Following these steps will help you generate a token smoothly and reduce onboarding friction.

Setup

Installation

To install the Axeptio React Native SDK, run one of the following commands:

Using npm:

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

Using yarn:

yarn add @axeptio/react-native-sdk

Android Setup

• Minimum SDK version: 26.
• Add the Maven GitHub repository and credentials to your app's android/build.gradle (located at the root level of your .gradle file). The snippet below is added to your android/build.gradle file, in the repositories block. It configures Gradle to pull the Axeptio Android SDK from a private GitHub repository.
• Your [GITHUB_TOKEN] scopes need [read:packages, repo]

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/axeptio/axeptio-android-sdk")
            credentials {
                username = "[GITHUB_USERNAME]"
                password = "[GITHUB_TOKEN]"
            }
        }
    }
}

iOS Setup

• We support iOS versions >= 15.
• Run the following command to install the dependencies:

npx pod-install

You can find a basic usage of the Axeptio SDK in the example folder. Please check the folder for more detailed implementation examples.

🚀Initialize the SDK on App Startup

To initialize the Axeptio React Native SDK in your app, you need to set it up when your application starts. The SDK can be configured for different use cases, such as brands or publishers, using the AxeptioService enum. This allows you to customize the SDK according to your specific needs (e.g., handling GDPR consent for brands or publishers).

Here’s a step-by-step guide on how to initialize the SDK:

import AxeptioSDK, { AxeptioService } from '@axeptio/react-native-sdk';

async function init() {
  try {
    // Initialize the SDK with the desired service (brands or publishers)
    await AxeptioSDK.initialize(
      AxeptioService.brands, // Choose between AxeptioService.brands or AxeptioService.tcfPublishers
      [your_client_id],      // Replace with your client ID (as provided by Axeptio)
      [your_cookies_version], // Replace with your current cookies version (as defined by your platform)
      [optional_consent_token] // Optional: If available, provide an existing consent token to restore previous consent choices
    );

    // Setup the user interface for consent management
    await AxeptioSDK.setupUI();

    console.log("Axeptio SDK initialized successfully!");
  } catch (error) {
    console.error("Error initializing Axeptio SDK:", error);
  }
}

Parameters:

• AxeptioService: This enum defines the type of service you’re using:
  • AxeptioService.brands: Use this for brands and advertisers. This setup is typically used for compliance with GDPR and other privacy regulations for tracking user consent.
  • AxeptioService.tcfPublishers: Use this for publishers. It helps with managing user consent under the Transparency and Consent Framework (TCF) , which is common for handling GDPR consent in the context of digital publishing.
• your_client_id: Replace this with your unique client ID provided by Axeptio when you set up your account. This ID identifies your organization or application in the system.
• your_cookies_version: This is a version identifier for your cookies. It helps manage different cookie policies and consent flows over time. This value should be incremented when your cookie policy changes.
• optional_consent_token: This token (if available) allows you to pass a previously stored consent token to restore the user's previous consent choices. This is optional, and you can skip it if it's not required.

ATT (App Tracking Transparency) Integration Note:

The Axeptio SDK does not handle the user permission for tracking in the App Tracking Transparency (ATT) framework. It is the responsibility of your app to manage this permission and decide how the Axeptio Consent Management Platform (CMP) and the ATT permission should coexist.

Apple Guidelines

Your app must comply with Apple's guidelines for disclosing the data collected by your app and requesting the user's permission for tracking.

To manage ATT, you can use the react-native-tracking-transparency widget.

• ATT Flow: Ensure that the ATT prompt is displayed to the user before you ask for consent in the Axeptio CMP. This ensures that you comply with Apple's privacy requirements.
• Apple's ATT Guidelines: Make sure that you follow Apple's ATT guidelines for proper implementation.

Steps to Integrate ATT:

• Install the library: You need to install the react-native-tracking-transparency library to handle ATT requests.

Using npm:

   npm install --save react-native-tracking-transparency

Or using yarn:

yarn add react-native-tracking-transparency

• Update Info.plist: Add the following key to your Info.plist file to explain why your app requires user tracking:

<key>NSUserTrackingUsageDescription</key>
<string>Explain why you need user tracking</string>

• Manage the ATT Popup: Before displaying the Axeptio CMP UI, you need to request ATT permission and handle the user's response. Here's how you can manage the ATT popup:

import { getTrackingStatus, requestTrackingPermission } from 'react-native-tracking-transparency';

async function handleATT() {
  // Check the current tracking status
  let trackingStatus = await getTrackingStatus();

  // If status is not determined, request permission
  if (trackingStatus === 'not-determined') {
    trackingStatus = await requestTrackingPermission();
  }

  // If tracking is denied, update the Axeptio SDK with the user's decision
  if (trackingStatus === 'denied') {
    await AxeptioSDK.setUserDeniedTracking();
  } else {
    // If tracking is allowed, initialize the Axeptio SDK UI
    await AxeptioSDK.setupUI();
  }
}

🧑‍💻Responsibilities: Mobile App vs SDK

The Axeptio SDK and your mobile application have distinct responsibilities when it comes to managing user consent and tracking:

Mobile Application Responsibilities:

• Implementing and managing the App Tracking Transparency (ATT) permission flow.
• Deciding when to show the ATT prompt in relation to the Axeptio CMP.
• Properly declaring data collection practices in App Store privacy labels.
• Handling SDK events and updating app behavior based on user consent.

Axeptio SDK Responsibilities:

• Displaying the consent management platform (CMP) interface.
• Managing and storing user consent choices.
• Sending consent status through APIs.

Important: The SDK does not automatically handle ATT permissions. These must be explicitly managed by the host application, as shown in the implementation examples above.

Get Stored Consents

You can retrieve the consents that are stored by the Axeptio SDK in UserDefaults (iOS) or SharedPreferences (Android). This allows your app to access the consent status even after the app has been closed and reopened.

iOS (UserDefaults)

For iOS, consents are stored in the UserDefaults system. You can use the standard UserDefaults API to access and retrieve the consent data.

// Example for retrieving consents in iOS
let consentStatus = UserDefaults.standard.string(forKey: "axeptioConsentStatus")

Android (SharedPreferences)

For Android, consents are stored in SharedPreferences. You can access them using the standard SharedPreferences API to retrieve the stored consent status.

// Example for retrieving consents in Android
SharedPreferences prefs = context.getSharedPreferences("axeptio", Context.MODE_PRIVATE);
String consentStatus = prefs.getString("axeptioConsentStatus", "default_value");

Accessing Consent Status in SDK

To directly retrieve consent data using the Axeptio SDK, you can use the following methods:

// Example in JavaScript (React Native)
const consentStatus = await AxeptioSDK.getConsentStatus();

To access UserDefaults (iOS) or SharedPreferences (Android), you can utilize the react-native-default-preference library, which provides a unified interface for both platforms.

Show Consent Popup on Demand

You can trigger the consent popup to open at any time during the app's lifecycle. To show the consent popup, use the following method:

AxeptioSdk.showConsentScreen();

Sharing Consents with Other Web Views

This feature is available only for the Publishers service.

The SDK provides a helper function to append the axeptio_token query parameter to any URL. You can either use the current user token stored in the SDK or pass a custom token.

const token = await AxeptioSdk.getAxeptioToken();
const url = await AxeptioSdk.appendAxeptioTokenURL(
  'https://myurl.com',
  token
);

// The resulting URL will be:
// https://myurl.com?axeptio_token=[token]

Clear Users Consent Choices

To clear the consent choices stored by the SDK, use the following method:

AxeptioSdk.clearConsent();

This will remove all the stored consent data.

Events

The Axeptio SDK triggers various events to notify the app when the user has taken actions related to consent.

To handle these events, you can add an AxeptioEventListener. This allows you to react to events such as the consent popup being closed or updates to Google Consent Mode.

const listener: AxeptioEventListener = {
  onPopupClosedEvent: () => {
    // Retrieve consents from UserDefaults/SharedPreferences
    // Check user preferences
    // Run external processes/services based on user consents
  },

  onGoogleConsentModeUpdate: (_consents) => {
    // Handle Google Consent V2 status update
    // You can take further actions based on the consent state
  },
};

// Add the listener to the Axeptio SDK
AxeptioSDK.addListener(listener);

For more detailed information, you can visit the Axeptio documentation. We hope this guide helps you get started with the Axeptio React Native SDK. Good luck with your integration, and thank you for choosing Axeptio!