Installation

This section provides detailed instructions for installing the AppTrove React Native SDK in your React Native project, enabling tracking of user interactions, attribution, and campaign analytics for Android and iOS platforms. The installation process involves adding the SDK package, installing dependencies, and configuring platform-specific settings to support features like Google Advertising ID.

Prerequisites

• React Native 0.60 or later
• Node.js and npm for package management
• A Trackier MMP account with access to the Trackier Panel
• For Android:
  • Android API 21 (Android 5.0) or later
  • Gradle for dependency management
• For iOS:
  • iOS 10.0 or later
  • Xcode 12.0 or later
  • CocoaPods for dependency management
• Internet connection for downloading the SDK package

Add AppTrove SDK to Your App

To integrate the AppTrove React Native SDK, install the SDK package using npm and configure dependencies for both Android and iOS platforms.

Step 1: Install the SDK Package

1. Open a terminal in your React Native project root directory.
2. Run the following command to install the AppTrove React Native SDK:

npm install trackier/react-native-sdk

Step 2: Install iOS Dependencies

For iOS, install CocoaPods dependencies to ensure the SDK integrates correctly.

1. Navigate to the ios folder in your project directory:

cd ios

1. Install CocoaPods dependencies:

pod install

1. Return to the project root directory:

cd ..

Expected Outcome

The SDK will be added to your project's node_modules, and iOS dependencies will be installed in the ios/Pods directory. The project is now ready for platform-specific configurations.

Update Android Configuration

To support tracking features like Google Advertising ID, configure your Android project with the necessary dependencies and permissions.

Step 1: Add Google Advertising ID Dependency

1. Open the android/app/build.gradle file.
2. Add the Google Play Services Ads Identifier dependency to the dependencies section:

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}

Step 2: Update Gradle Properties (if needed)

If your project uses a Gradle version lower than 7.0, update the android/gradle.properties file to include the following line to ensure compatibility:

android.jetifier.blacklist=moshi-1.13.0.jar

Step 3: Update Android Manifest

1. Open the android/app/src/main/AndroidManifest.xml file.
2. Add the following permission to support devices running Android 12 or later:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

1. Add the Google Play Services version meta-data inside the <application> tag (if not already present):

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Step 4: Sync Gradle

1. Open the android directory in a terminal:

cd android

1. Run the following command to sync the project with the updated Gradle configuration:

./gradlew cleanBuildCache

1. Return to the project root directory:

cd ..

Update iOS Configuration

note

The React Native SDK README specifies only CocoaPods installation for iOS. Additional configurations (e.g., Info.plist updates for permissions) are not detailed. Provide specific details to refine this section.

To ensure proper iOS integration, verify the CocoaPods setup and apply any necessary project configurations.

Step 1: Verify CocoaPods Installation

1. Confirm that the pod install command completed successfully, creating a Podfile.lock file in the ios directory.
2. Open the .xcworkspace file in Xcode (not .xcodeproj) to build the iOS project.

Step 2: Add iOS Permissions (if applicable)

note

Add specific iOS configurations (e.g., NSUserTrackingUsageDescription for App Tracking Transparency) if required.

1. Open the ios/[YourAppName]/Info.plist file in Xcode or a text editor.
2. Add any required permissions, such as:

<key>NSUserTrackingUsageDescription</key>
<string>We use tracking data to improve your app experience.</string>

1. Save the file and rebuild the iOS project.

Best Practices

• Use the Latest SDK Version: Regularly check for updates to the trackier/react-native-sdk package on npm to ensure compatibility and access to new features.
• Backup Your Project: Save a backup of your React Native project before installing the SDK to prevent data loss.
• Verify Dependency Installation: Confirm that node_modules/trackier/react-native-sdk exists and that iOS Pods are installed correctly.
• Test Platform Configurations: Build and test on both Android and iOS to ensure the SDK and Google Advertising ID configurations work as expected.
• Secure Manifest Files: Store AndroidManifest.xml changes in version control and avoid exposing sensitive data.

Troubleshooting

• NPM Installation Fails:
  • Ensure you have an active internet connection and the correct npm version.
  • Run npm cache clean --force and retry npm install trackier/react-native-sdk.
• CocoaPods Installation Fails:
  • Verify that CocoaPods is installed (pod --version) and up to date (gem install cocoapods).
  • Check for errors in the terminal output during pod install and resolve dependency conflicts.
• Google Advertising ID Not Retrieved:
  • Confirm the com.google.android.gms:play-services-ads-identifier dependency is correctly added in build.gradle.
  • Ensure the com.google.android.gms.permission.AD_ID permission is included in AndroidManifest.xml for Android 12+ devices.
• Build Errors on Android/iOS:
  • Check Gradle sync errors in Android Studio or terminal output.
  • For iOS, ensure you're opening the .xcworkspace file in Xcode. For further assistance, refer to the Trackier Documentation Portal or contact Trackier support at support@trackier.com.