Module Integration

lucra-react-native-sdk

Pre-Installation

The package works in both the new and old architecture.

You will need to specify our private native dependencies as they are hosted in GitHub packages. There are two ways to install a private dependency.

You need to create a Personal Access Token (PAT)

Managing Personal Access Tokens

Select "Classic" with the packages:read and repo permissions enabled and name it Lucra Token. When installing the native dependencies you will be prompted for your username and this token. In case you are setting up a CI system you will also have to use this token in a combination with a username.

Installation

NPM

After you have your token you need to create a .npmrc file at the root of your project and you need to tell the package needs to be fetched from the github registry:

//npm.pkg.github.com/:_authToken=GITHUB_PERSONAL_TOKEN
@lucra-sports:registry=https://npm.pkg.github.com

Install the package to your React Native Repo by running:

npm i -s @lucra-sports/lucra-react-native-sdk

Usually you don't want to commit this file into the git repo history. So it's better to add it to your gitignore and each user on your organization has their own file and CI as well.

Integrating with an Expo React Native App

This section provides instructions on how to integrate Lucra SDK into your Expo React Native application. The steps cover both iOS and Android platforms, focusing on projects that use expo prebuild or have been ejected, resulting in their own ios and android directories.

Note: This integration does not work with Expo Go, as Expo Go does not support custom native modules. You will need to build a standalone app using Expo's build services or build it locally.

Expo Setup

To install the SDK in your Expo app, you have two main options:

1. Use Prebuild or Eject Your App: If your app uses expo prebuild or has been ejected, you can follow the platform-specific installation steps for each platform as detailed below.

2. Use lucra-react-native-sdk expo plugin: To avoid manual customization of the native directories, you can adjust your app.config.js file and utilize the provided Expo plugins to handle the necessary configurations.

Using the Expo Build Properties Plugin

The expo-build-properties plugin allows you to modify native build properties directly from your app.config.js. This is useful for setting deployment targets and specifying frameworks without touching the native code.

Update your app.config.js file with the following configuration to set the iOS deployment target and android minSDKVersion:

    plugins: [
      [
        'expo-build-properties',
        {
          ios: {
            deploymentTarget: '15.1',
            // The lucra SDK uses third-party services that require network inspection to be kept off.
            networkInspector: false,
          },
          android: {
            minSdkVersion: 24,
            networkInspector: false,
          },
        },
      ],
      '@lucra-sports/lucra-react-native-sdk',
    ],

Using Custom Fonts

Follow the guidelines on installing expo-font plugin and configure it to load the fonts. This will make the fonts available on android and iOS.

For android just pass the path of each font relative to "fonts/"

For iOS pass the font's familiy name Note: The current iOS implementation will use the font's family name and search for Bold, Regular and SemiBold variations, please make sure to provide all of them to properly replace the font for each UI element.

Using Expo Dev Client

When working with expo-dev-client, it's essential to disable the EX_DEV_CLIENT_NETWORK_INSPECTOR variable, The SDK uses third-party libraries that block network inspection. To ensure that EX_DEV_CLIENT_NETWORK_INSPECTOR is turned off make sure networkInspector is false when using expo-build-properties.

Setup Venmo deeplinks with Expo

Make sure to add the required Info.plist changes to the iOS section in order to support Venmo callback urls and deeplinks:

      infoPlist: {
        CFBundleURLTypes: [
          {
            CFBundleURLSchemes: ['YOUR_APP_BUNDLE_IDENTIFIER.venmo'],
            CFBundleURLName: 'Venmo URL Scheme',
          },
        ],
        LSApplicationQueriesSchemes: ['venmo', 'com.venmo.touch.v2'],
      },

iOS

The minimum target version is iOS 15.1, so you will also have to update this on your project (You can do it in the XCode general tab) and in your podfile:

platform :ios, 15.1

In your ios folder Podfile:

Add the following lines to the top of your Podfile to allow Cocoa Pods to find our native SDK dependency, check out the example Podfile for a reference:

source 'https://github.com/Lucra-Sports/lucra-ios-sdk.git'

# Independent of which method you choose, always add these
source 'https://cdn.cocoapods.org/'

use_frameworks! linkage: :static

Flipper

If you are using Flipper. you will need to disable Flipper as it fails to link when using `use_frameworks!``:

# You can either comment out this line
# :flipper_configuration => flipper_config,

# Or choose the disabled configuration
flipper_config = FlipperConfiguration.disabled

Flipper has been removed in the latest React-Native versions, so this might not apply to your app.

New Arch

The package is compatible with the new arch. There is however one problem with embedded views on Android. They don't work because they are made with Android Compose, which is not supported by react-navigation/react-native-screens. If you need embedded components for now you will have to stick to the old arch.

Add Lucra private pod repo

Run the following command to add the native SDK dependency locally that you added previously as a source in the Podfile

# In a local machine you can add it directly
pod repo add LucraSDK https://github.com/Lucra-Sports/lucra-ios-sdk
# OR
pod repo add LucraSDK [email protected]/Lucra-Sports/lucra-ios-sdk

# If setting up in a CI you will need the Personal Access token you first created and a username
# Here is an example for GitHub Actions. Add LUCRA_USERNAME and LUCRA_TOKEN in the secrets section of the GitHub repository
- name: Add private repo to cocoapods
  run: pod repo add LucraSDK https://${{secrets.LUCRA_USERNAME}}:${{secrets.LUCRA_TOKEN}}@github.com/Lucra-Sports/lucra-ios-sdk.git

Permissions

The following keys will need to be set in Info.plist or the binary may be rejected and the app will crash.

NSBluetoothAlwaysUsageDescription
NSBluetoothPeripheralUsageDescription
NSFaceIDUsageDescription
NSLocalNetworkUsageDescription
NSLocationAlwaysAndWhenInUseUsageDescription
NSLocationAlwaysUsageDescription
NSLocationWhenInUseUsageDescription
NSMotionUsageDescription
NSCameraUsageDescription
NSPhotoLibraryUsageDescription

Firebase

If using firebase some additional steps are required, start by following the general setup https://rnfirebase.io/

Make sure to enable firebase to use static frameworks editing your /ios/Podfile:

# right after `use_frameworks! :linkage => :static`
$RNFirebaseAsStaticFramework = true

Android

Lucra Android Native SDK artifacts are privately hosted on https://github.com/Lucra-Sports/lucra-android.

You will need the personal access token (PAT) created above to pull these packages at build time.

See how to create personal access token

Place credentials on local machine and build server

Once a PAT is obtained, you will need to store them on your machine for building locally and in your system environment for build pipelines. The SDK will look for the gradle.properties first then fallback on the System.env property.

Set PAT for local Android development

Place the following lines either on your machine's (Linux/Mac) ~ .gradle/gradle.properties file (create one if it doesn't exist), or in your Android project's gradle.properties file. If you use your Android project's gradle.properties file, be sure to not check this into your repo.

GPR_USER=YOUR_USERNAME
GPR_KEY=YOUR_PAT

Set PAT for Android CI/CD pipelines

In order to build the project on your pipelines, the system env variables should be set.

build-android:
  runs-on: ubuntu-latest
  env:
    #fetch from GitHub secrets or similar, don't check PATs into the build code
    GPR_USER: YOUR_USERNAME
    GPR_KEY: YOUR_PAT
    # ...

Both approaches work for local and build servers, but ~ .gradle/gradle.properties for local development and env: for build pipelines are the best ways to keep your PATs safe.

Provide GPR Access with GPR credentials

After GPR_USER and GPR_KEY are correctly fetched at build time, you'll then need to provide repository access for gradle to resolve the private artifacts at build time.

In your root Android project's build.gradle

  allprojects {
    repositories {
      maven {
        name = "LucraGithubPackages"
        url = uri("https://maven.pkg.github.com/Lucra-Sports/lucra-android")
        credentials {
          username = findProperty('GPR_USER') ?: System.getenv('GPR_USER')
          password = findProperty('GPR_KEY') ?: System.getenv('GPR_KEY')
        }
      }
      maven {
        url "https://zendesk.jfrog.io/zendesk/repo"
      }
    }
  }

Android Auth0 compliance (if not already using Auth0)

We use Auth0 for auth, if your app doesn't use it already, add the following to your app's default config.

android {
  defaultConfig {
    manifestPlaceholders = [
      'auth0Domain': 'LUCRA_SDK',
      'auth0Scheme': 'LUCRA_SDK'
    ]
  }
}

Min API version

LucraSDK requires a minimum API version of 24, you will have to update your project to bump this:

// android/build.gradle
buildscript {
  ext {
    buildToolsVersion = "34.0.0"
    minSdkVersion = 24 // <-------- MAKE SURE THIS IS AT LEAST 24
    compileSdkVersion = 34
    ndkVersion = "25.1.8937393"
    targetSdkVersion = 34
    kotlinVersion = "1.8.0"
  }

Manifest Requirements

The following manifest permissions, features, receivers and services are required to use Lucra

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" <!-- DO NOT SKIP! -->
>
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
    <uses-permission android:name="android.webkit.PermissionRequest" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
    <uses-feature android:name="android.hardware.camera.autofocus" />
    <uses-feature android:name="android.hardware.camera" />

    <application
    ...
    >

    <!--    Geocomply requirements-->
    <receiver android:name="com.geocomply.client.GeoComplyClientBootBroadcastReceiver"
        android:enabled="true" android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.BOOT_COMPLETED" />
            <action android:name="android.intent.action.QUICKBOOT_POWERON" />
        </intent-filter>
    </receiver>

    <service android:name="com.geocomply.location.WarmingUpLocationProvidersService"
        android:exported="false" />
    <service android:name="com.geocomply.security.GCIsolatedSecurityService"
        android:exported="false" android:isolatedProcess="true" tools:targetApi="q" />

    <receiver android:name="com.geocomply.client.GeoComplyClientBroadcastReceiver" />
</application>
</manifest>

Application Requirements

Lucra leverages Coil to render images and SVGs. In your application class, provide the LucraCoilImageLoader

// Don't forget to set the app manifest to use this Application
class MyApplication : Application(), ImageLoaderFactory {
    // Use Lucra's ImageLoader to decode SVGs as needed
    override fun newImageLoader() = LucraCoilImageLoader.get(this)
}

Firebase

You will need to add the firebase crashlytics plugin to your app's configuration.

First on your android/build.gradle file add the dependency to the buildscript:

  dependencies {
    // Your other buildscript dependencies
    classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.8' // Add this
  }

Next edit your android/app/build.gradle file. At the top of the file apply the plugin:

// Your other plugins
apply plugin: "com.google.firebase.crashlytics" // Add this

Initialize the Lucra SDK

API Key Update (Required)

Starting with React Native SDK 5.0.0+, Lucra SDK initialization requires a new apiKey.

Docs will be updated once this verison is available

What changed

• A new apiKey is required during Lucra SDK initialization.

• The previous apiKey + apiUrl initialization pattern is no longer supported.

• Existing integrations on older SDK versions continue to function as-is.

Required action

• Update your Lucra SDK initialization to pass the new apiKey at runtime.

• Remove prior apiUrl reference.

Notes

• The apiKey used prior to this version will not work once this latest version is adopted.

• Please reach out to Lucra to obtain your new Sandbox and Production keys.

• Backend API keys are unchanged.

Import the SDK from the @lucra-sports/lucra-react-native-sdk package, you must initialize the SDK with an API key and an environment before anything else. The initialization is a promise since communication with the backend is async and required on init.

import { LucraSDK } from '@lucra-sports/lucra-react-native-sdk';
import React from 'react';
import { Button, StyleSheet, View } from 'react-native';

let lucraSDKOptions = {
  apiURL: <insert your url here>,
  apiKey: <insert your key here>,
  environment: LucraSDK.ENVIRONMENT.SANDBOX,
  theme: {
    background: '#001448',
    surface: '#1C2575',
    primary: '#09E35F',
    secondary: '#5E5BD0',
    tertiary: '#9C99FC',
    onBackground: '#FFFFFF',
    onSurface: '#FFFFFF',
    onPrimary: '#001448',
    onSecondary: '#FFFFFF',
    onTertiary: '#FFFFFF',
    // Fonts
    //
    // For iOS you need to pass the cannonical name of your linked font
    // You can find this by opening your font files in FontBook
    //
    // For android you need to pass the path inside the Android assets folder
    // If you have linked your assets using the default location /assets/fonts
    // Then the android linked fonts should land in /android/app/src/main/assets/font
    // and the configuration should match the one below. You must specify all four keys.
    fontFamily:
      Platform.OS === 'ios'
        ? 'Inter'
        : {
            normal: 'fonts/Inter-Regular.ttf',
            bold: 'fonts/Inter-Bold.ttf',
            semibold: 'fonts/Inter-SemiBold.ttf',
            medium: 'fonts/Inter-Medium.ttf',
          },
  },
};

export default function App() {
  const [isReady, setIsReady] = useState(false)
  useEffect(() => {
    LucraSDK.init(lucraSDKOptions).then(() => {
      setIsReady(true)
    })
  }, [])

  if(!isReady){
    return null
  }

  return (<>...</>);
}