Skip to main content

Installation

SDK Version Selection

Choose your SDK version below:

  • Apptrove SDK → Recommended for all projects (Latest: v2.x.x)
  • Trackier SDK → Will be deprecated in August 2026 (Latest legacy: v1.x.xx)

Use the tabs below for SDK-specific snippets.

This section provides detailed instructions for installing the Apptrove Cordova SDK (Apptrove recommended, Trackier legacy optional) in your Cordova 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 and Android Install Referrer.

Prerequisites​

  • Cordova 9.0 or later
  • Node.js and npm for package management
  • For Ionic Native apps:
    • Ionic CLI and Capacitor for project synchronization
    • @awesome-cordova-plugins/core package
  • 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
  • Apptrove account with access to the Apptrove Panel
  • Internet connection for downloading the SDK package

Add Apptrove SDK to Your App​

To integrate the Apptrove Cordova SDK (Apptrove recommended, Trackier legacy optional), install the SDK package using npm and configure dependencies for both Android and iOS platforms, with additional steps for Ionic Native apps.

Step 1: Install the SDK Package​

  1. Open a terminal in your Cordova project root directory.
  2. Run the install command for your selected SDK:
npm install ApptroveLabs/cordova_sdk#ApptroveSDK

Step 2: Install Dependencies for Ionic Native (if applicable)​

For Ionic Native apps, additional plugins and synchronization are required.

  1. Install the Awesome Cordova Plugins core package:
npm install @awesome-cordova-plugins/core --save
  1. Synchronize Capacitor dependencies:
ionic cap sync
  1. Use Apptrove import path directly in Ionic Native code:
    • com.apptrove.cordova_sdk/ionic-native/apptrove/ngx
    • No manual plugin folder copy is required.

Expected Outcome​

The SDK will be added to your project's node_modules. For Apptrove imports, no extra plugin folder setup is required. If you are maintaining the legacy Trackier import path, ensure the trackier folder exists in @awesome-cordova-plugins.

Update Android Configuration​

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

Step 1: Add Android Install Referrer Dependency​

  1. Open the android/app/build.gradle file.
  2. Add the Android Install Referrer dependency to the dependencies section:
dependencies {
    implementation 'com.android.installreferrer:installreferrer:2.2'
}

Step 2: Add Google Advertising ID Dependency​

  1. In the same android/app/build.gradle file, add the Google Play Services Ads Identifier dependency:
dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}

Step 3: Update Android Manifest​

  1. Open the android/app/src/main/AndroidManifest.xml file.
  2. Add the following permissions to support network access and Google Advertising ID:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" />
<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. Navigate to 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​

To ensure proper iOS integration, synchronize and build the iOS project, and add any required permissions for optional features.

Step 1: Sync and Build iOS​

  • Ionic Native (Capacitor):
    1. Run ionic cap sync ios
    2. Open ios/App/App.xcworkspace in Xcode
  • Cordova:
    1. Run cordova platform add ios (if needed)
    2. Run cordova build ios

Step 2: Add iOS Permissions (Optional)​

If you use App Tracking Transparency (ATT) / IDFA on iOS 14.5+, add NSUserTrackingUsageDescription to your Info.plist and implement the ATT flow. See: App Tracking Transparency (ATT)

Best Practices​

  • Use the Latest SDK Version: Track updates in the Apptrove Cordova SDK repository and release notes, and keep your integration pinned to the required branch/version.
  • Backup Your Project: Save a backup of your Cordova project before installing the SDK to prevent data loss.
  • Verify Dependency Installation: Confirm that node_modules/com.apptrove.cordova_sdk (or your configured package alias) exists. For legacy Trackier imports only, verify the trackier folder in @awesome-cordova-plugins.
  • Test Platform Configurations: Build and test on both Android and iOS to ensure the SDK, Google Advertising ID, and Install Referrer configurations work as expected.
  • Secure Manifest Files: Store AndroidManifest.xml changes in version control and avoid exposing sensitive data.
  • Follow Ionic Native Steps: For Ionic apps, run ionic cap sync after dependency changes. Manual plugin placement is required only for legacy Trackier import setups.

Troubleshooting​

  • NPM Installation Fails:
    • Ensure an active internet connection and the correct npm version.
    • Run npm cache clean --force and retry the install command for your SDK:
      • npm install ApptroveLabs/cordova_sdk#ApptroveSDK (Apptrove)
      • npm install ApptroveLabs/cordova_sdk (Trackier legacy)
  • Ionic Native Plugin Not Found:
    • Confirm @awesome-cordova-plugins/core is installed and ionic cap sync has been executed.
    • Verify the import path matches your SDK:
      • com.apptrove.cordova_sdk/ionic-native/apptrove/ngx for Apptrove SDK.
      • @awesome-cordova-plugins/trackier/ngx for legacy Trackier SDK.
    • If using the legacy Trackier import path, ensure the trackier folder is present in node_modules/@awesome-cordova-plugins.
  • Google Advertising ID Not Retrieved:
    • Confirm the com.google.android.gms:play-services-ads-identifier dependency is added in build.gradle.
    • Ensure the com.google.android.gms.permission.AD_ID permission is included in AndroidManifest.xml for Android 12+ devices.
  • Install Referrer Not Working:
    • Verify the com.android.installreferrer:installreferrer dependency is correctly added in build.gradle.
    • Test the referrer setup using Google Play Store's testing tools.
  • Build Errors on Android/iOS:
    • Check Gradle sync errors in Android Studio or terminal output.
    • For iOS, ensure the .xcworkspace file is used in Xcode for Ionic Native apps.

For further assistance, refer to the Apptrove Documentation Portal or contact Apptrove support at support@apptrove.com.