React Native Honeygain SDK Integration guide

This short guide informs how to integrate Honeygain SDK plugin into your React Native project.

info

Don't forget to generate your Honeygain SDK API Key and download SDK from Developers dashboard first.

warning

Restriction for Google Play Apps. SDK cannot be integrated into applications distributed via Google Play. Minimum required Android API level is 21 (Android 5.0 / Lollipop). Also for Google Play integration you MUST talk to your account manager or someone from [email protected].

Installation

1. Add honeygain-react-native-sdk to your project dependencies: (Substitute x.x.x with the SDK version you are using, e.g. 1.0.0)

npm

npm install ./honeygain-react-native-sdk-x.x.x.tgz

Yarn

yarn add ./honeygain-react-native-sdk-x.x.x.tgz

2. For iOS, install the pods:

cd ios && pod install

SDK setup

The SDK provides a useHgSdk hook as the primary interface for React developers. This hook handles SDK initialization and provides access to all SDK functionality.

Initialization

The SDK must be initialized with an API key before any other operations can be performed. When using the useHgSdk hook, initialization happens automatically when the hook is first called.

const { ... } = useHgSdk(API_KEY);

Usage

You should call the hook in your root component or a top-level provider, passing your API key.

You need to get a legal consent from the user before starting SDK (SDK will not start without user consent). The simplest way to do that is to call requestConsent.trigger() from the hook.

After consent is provided, you can call start.trigger().

App.tsx

import React, { useEffect } from 'react';
import { Button, View, Text } from 'react-native';
import { useHgSdk } from 'honeygain-react-native-sdk';

const API_KEY = "<your-api-key>";

function App() {
  const {
    start: { trigger: startSdk },
    stop: { trigger: stopSdk },
    isOptedIn: { result: isOptedIn, trigger: getOptedIn },
    isRunning: { result: isRunning, trigger: getRunning },
    requestConsent: { trigger: requestConsent },
  } = useHgSdk(API_KEY);

  useEffect(() => {
    // Periodically check SDK status
    const interval = setInterval(() => {
      void getOptedIn();
      void getRunning();
    }, 2000);
    return () => clearInterval(interval);
  }, [getOptedIn, getRunning]);

  const handleStart = async () => {
    // Show consent if not opted in
    if (!isOptedIn) {
      await requestConsent();
    }

    // Start SDK if opted in
    // Note: check the latest state after requestConsent
    await startSdk();
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Opted In: {JSON.stringify(isOptedIn)}</Text>
      <Text>Running: {JSON.stringify(isRunning)}</Text>

      <Button title="Start SDK" onPress={handleStart} />
      <Button title="Stop SDK" onPress={() => stopSdk()} />
    </View>
  );
}

export default App;

Stopping SDK

Call stop.trigger() from the useHgSdk hook.

Withdraw the consent

User should be able to opt out from using SDK at any time. When user does so within your app, you should call optOut.trigger() function, which will immediately stop SDK and will no longer start it unless user grants consent again.

Running in background (Android)

warning

In most cases if SDK is not allowed to run in background, it will only run for a short while after your application is closed, because Android system will shut it down.

In the React Native SDK, background execution is enabled by default upon initialization. However, you need to add the required permissions to your AndroidManifest.xml for it to function correctly.

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Permissions for background functionality -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />

    <application>
    </application>
</manifest>

Running in background (iOS)

Depending on your application's use case, you can enable Location updates or Audio, AirPlay and Picture in Picture background modes, so that your application and the SDK would be performant while in background.

• To enable background mode for the Location updates use-case:

• In your application target settings select -> Signing & Capabilities -> + Capability -> Background Modes;

• In the Background Modes section, select Location updates and Background processing checkboxes.

• To enable background mode for Audio, AirPlay and Picture in Picture use case:

• In your application target settings select -> Signing & Capabilities -> + Capability -> Background Modes;

• In the Background Modes section, select Audio, AirPlay and Picture in Picture and Background processing checkboxes.

warning

Logic for audio playback or location updates usage has to be implemented by application's developer for extended runtime in background mode to be allocated by the iOS.

Custom consent window

If default SDK consent window doesn't suit your needs, you can create a custom consent window. Make sure to call optIn.trigger() whenever user gives a consent and optOut.trigger() whenever user declines it.

warning

Custom consent screen must be approved by our team to maintain clarity for end user.

Custom Consent Example

const { optIn, optOut, start } = useHgSdk(API_KEY);

const handleCustomConsentAccept = async () => {
  await optIn.trigger();
  await start.trigger();
};

const handleCustomConsentDecline = async () => {
  await optOut.trigger();
};

Logging

You can enable SDK logging to check if SDK is integrated correctly.

Enable Logging Example

const { enableLogging } = useHgSdk(API_KEY);

useEffect(() => {
  enableLogging.trigger(true);
}, []);

SDK API Reference

The useHgSdk hook returns an object containing the following properties. Each property represents an async operation and contains result, trigger, loading, and error states.

Property	Description
identify	Returns the unique identifier for the device SDK.
requestConsent	Displays the default SDK consent window (only if not opted in).
optIn	Marks the user as opted-in (used for custom consent UI).
optOut	Marks the user as opted-out and stops the SDK.
isOptedIn	Returns whether the user has given consent.
start	Starts the SDK if consent was given.
stop	Stops the SDK.
isRunning	Returns whether the SDK is currently running.
enableLogging	Enables or disables SDK logging.

Each trigger function returns a Promise that resolves with the operation result.