Installation

This section provides detailed instructions for installing the Trackier Cordova SDK 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
• Trackier MMP account with access to the Trackier Panel
• Internet connection for downloading the SDK package

Add AppTrove SDK to Your App

To integrate the Trackier Cordova SDK, 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 following command to install the Trackier Cordova SDK:

npm install trackier/cordova_sdk

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. Download the Trackier plugin folder from GitHub.
2. Copy the trackier folder into the node_modules/@awesome-cordova-plugins directory.

Expected Outcome

The SDK will be added to your project's node_modules, and for Ionic Native apps, the trackier folder will be correctly placed in @awesome-cordova-plugins. The project is now ready for platform-specific configurations.

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

note

The Cordova SDK documentation specifies only Capacitor synchronization for Ionic Native apps. Additional iOS 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 Capacitor setup and apply any necessary project configurations.

Step 1: Verify Capacitor Synchronization

1. Confirm that the ionic cap sync command completed successfully, updating the iOS project in the ios directory.
2. Open the ios/App/App.xcworkspace file in Xcode 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/App/App/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/cordova_sdk package on npm to ensure compatibility and access to new features.
• 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/trackier/cordova_sdk exists and, for Ionic Native, the trackier folder is correctly placed 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, ensure all Ionic-specific steps (e.g., ionic cap sync, plugin placement) are completed to avoid integration issues.

Troubleshooting

• NPM Installation Fails:
  • Ensure an active internet connection and the correct npm version.
  • Run npm cache clean --force and retry npm install trackier/cordova_sdk.
• Ionic Native Plugin Not Found:
  • Verify the trackier folder is correctly placed in node_modules/@awesome-cordova-plugins.
  • Confirm @awesome-cordova-plugins/core is installed and ionic cap sync has been executed.
• 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 Trackier Documentation Portal or contact Trackier support at support@trackier.com.