Getting Started with OptiMobile

This integration guide will walk through a step by step integration, with checkpoints to test that the integration steps are complete and working.

At the end of the guide you should

  1. Have a mobile application with the Optimove SDK integrated
  2. Installs tracking into your Optimove UI
  3. Receive test push notifications directly to your device

Alternatively you can refer to the SDK Reference for a method-by-method explanation of the SDK's capabilities.

Prerequisites

Minimum iOS version: 10.0

Dependency Manager (optional)
- Xcode 11 or higher
- Cocoapods 1.5 or higher
- Carthage 0.30.0 or higher
Minimum Android API version: 21 (Lollipop) and higher
None
None
- iOS plugin installation requires CocoaPods. You can install CocoaPods
with the following command:
  
  sudo gem install cocoapods

  More information about CocoaPods can be found here: https://cocoapods.org/

- The plugin depends on Promises. Ensure you have a suitable promise 
polyfill available in your app runtime if required. 
You can find a suitable polyfill here: https://github.com/stefanpenner/es6-promise

Check the browser compatibility for Promises here: https://caniuse.com/#search=Promise
None

Versioning

Optimove uses semantic versioning, which means that each time you update, Optimove SDK will
automatically get updated with any minor features, improvements, and hot-fixes.

Credentials

In order to initialize the SDK you must provide credentials which can be retrieved from the Settings section of
Optimove UI (Settings > OptiMobile > Mobile Push Config > App Keys). To gain access to this, please make a request to the Optimove Product Integration team.

ℹ️

Optimove Mobile integration can begin as soon as you have received access to the Optimove UI, however tracking custom events and Track and Trigger functions require configuration with the Optimove Product Integration team.

Depending on which features were enabled for your app you will be able to retrieve the following credentials:

OPTIMOVE_CREDENTIALS – Your unique SDK token in order to identify your Optimove tenant
OPTIMOVE_MOBILE_CREDENTIALS – The mobile config used to identify your app bundle

ℹ️

The SDK can be initialized with either credential depending on which features are to be used, or both. But at least one must be provided to initialize.


Integration

📘

Supported Platforms

Our SDK supports both native and cross-platform development. For native platforms, it provides robust support for iOS (written in Swift) and Android (Java). Additionally, our SDK is compatible with cross-platform frameworks, including React Native, Flutter, Cordova, and Unity, ensuring a seamless integration experience across diverse app environments.

To add the SDK to your mobile app, follow the steps below:

/*
Contents:

1. Installation via SwiftPM
2. Installation via Cocoapods
3. Installation via Carthage
4. Setting up Capabilities


**************** 1. Installation via SwiftPM ****************

1. Open your Xcode project or workspace.
2. Add the https://github.com/optimove-tech/Optimove-SDK-iOS dependency with this instruction: https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app, and select:

   - OptimoveSDK
   - OptimoveNotificationServiceExtension


**************** 2. Installation via Cocoapods ****************

1. If you haven't already, use this guide to add Cocoapods to your project: 
	https://guides.cocoapods.org/using/using-cocoapods.html#creating-a-new-xcode-project-with-cocoapods
2. Open your Podfile.
3. Locate your App's target declaration.
4. Update your Podfile with the example: */
 
platform :ios, '10.0'
   use_frameworks!

   target '<YOUR_APP_NAME>' do
       pod 'OptimoveCore'
       pod 'OptimoveSDK'
   end

   target '<YOUR_NOTIFICATION_SERVICE_EXTENSION_NAME>' do
       pod 'OptimoveCore'
       pod 'OptimoveNotificationServiceExtension'
   end

/*
5. From your terminal, run pod install

6. Cocoapods will generate a Workspace file (*.xcworkspace). Use this workspace file from now on.


**************** 3. Installation via Carthage ****************

1. If you haven't already, install Carthage: https://github.com/Carthage/Carthage#installing-carthage
2. Create or update a Cartfile:

   github "optimove-tech/Optimove-SDK-iOS"

3. Run carthage update.
4. Choose a target for adding Optimove in an Xcode project.
5. Add the SDK to "Frameworks, Libraries, and Embedded Content" by dragging the new components 
from Carthage/Build/iOS, or selecting through the UI.

   Please, do not add OptimoveNotificationServiceExtension.framework to your Notification 
   Service Extension. Instead, add this framework to the hosted/main app and double-check 
   that LD_RUNPATH_SEARCH_PATHS of your Notification Service Extension contains 
   @executable_path/../../Frameworks.

   An example list of the added dependencies: [Image: The list of frameworks]

6. Add a New Run Script Phase for the App target's Build Phases, name it Carthage.

   6.1. Add the shell script to the Carthage's copy-framework phase:

      /usr/local/bin/carthage copy-frameworks

7. On this step, you could use separated lines for input/output files, but for this tutorial, 
we will describe a list file. Create .xcfilelist files according to steps 7.1 and 7.2. 
Or use already prepared .xcfilelist files from the source: 
https://github.com/optimove-tech/Optimove-SDK-iOS-Source-Code

   7.1. Add an input.xcfilelist file path under Input Files Lists. The file has to contain: */

   $(SRCROOT)/Carthage/Build/iOS/OptimoveCore.framework
   $(SRCROOT)/Carthage/Build/iOS/OptimoveSDK.framework
   $(SRCROOT)/Carthage/Build/iOS/OptimoveNotificationServiceExtension.framework

/*
   7.2. Add an output.xcfilelist file path under Output Files Lists. The file has to contain: */

   $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/OptimoveSDK.framework
   $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/OptimoveCore.framework
   $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/OptimoveNotificationServiceExtension.framework

/*
Important Note:
Use the "~>" operator to get the latest, backward-compatible, Optimove SDK seamlessly. 
Every time you run "cart update," you'll get the latest stable version.



**************** 4. Setting up Capabilities ****************

IMPORTANT: If you're upgrading the Optimove iOS SDK from a version earlier than 3.3.0, 
you must migrate from an AppGroup storage object to the shared defaults object by 
following the SDK setup instructions. If you're installing or upgrading to version 3.3.0 
or later, you can skip this section.

To set up the necessary capabilities, follow these steps in the Capabilities page for the 
App Target of your main application:

1. Enable the Push Notifications capability.  
2. Enable the Background Modes capability, and check both Remote notifications and Background fetch.  
3. Enable the App Groups capability, and add the following group: group.\<YOUR_APP_BUNDLE_ID>.optimove.
*/
/***************** Configure build.gradle *****************

1. Add the following to the app module's build.gradle file, under the android object */

   compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
   }

/*
2. For Kotlin support only:

Kotlin is completely interoperable with Java and Apps that are written in Kotlin can use the SDK.
However, these apps should add the following in addition to the compile options */

   compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
   }
   kotlinOptions {
       jvmTarget = '1.8'
   }

/* 
If you get an error like :app:transformClassesWithDesugarForDebug, you may have to 
enable desugaring in your gradle.properties file */

   android.enableD8.desugaring = true
   

/******** Add the Optimove repository to Your Project ********

1. Make sure that you have the mavenCentral() repository in your project level build.gradle file */

   buildscript {
       repositories {
           mavenCentral()
           //...
       }
       //...
   }

/*
2. In your app module's build.gradle file, update your dependency statement 
(under dependencies object) to */

   implementation 'com.optimove.android:optimove-android:7.+'

/*
   If after adding the dependency you get an error building like "Manifest merger failed", 
   follow the steps below to adjust Automatic Backup.

******************** Automatic Backup ********************

Starting from Android SDK version 23, Android offers the Auto Backup for Apps feature
as a way to back up and restore the user's data in the app.

The Optimove SDK depends on various local files being deleted once the app is uninstalled.
For that reason, if the hosting app also defines android:fullBackupContent="@xml/app_backup_rules" 
in the manifest.xml file, Android will raise a merge conflict.

Follow these steps to resolve the conflict and maintain the data integrity of the Optimove SDK:

- Add tools:replace="android:fullBackupContent" to the application tag.
- Copy the content of the optimove_backup_rules.xml to your full-backup-content xml.

If your target version is 31 and higher and your app defines 
android:dataExtractionRules="@xml/app_backup_rules", follow the same steps above.

If you consume SDK version higher or equal to 4.2.0 and your target version is lower 
than 31, add tools:remove="android:dataExtractionRules" to the application tag.

For more information about Android Automatic Backup, check out the backup 
Developer's Guide at https://developer.android.com/guide/topics/data/autobackup.html.
/*
npm install @optimove-inc/react-native
pod install --project-directory=ios
//1. Add the following dependency to your pubspec.yaml
dependencies:
  optimove_sdk_flutter: 1.0.0

//2. run:
pub install
/* To add the Optimove Cordova plugin to your project use the following in the 
root directory of your project. */

cordova plugin add @optimove-inc/cordova-sdk 
Optimove Unity SDK is distributed as a Unity package for importing into your projects. 
https://github.com/optimove-tech/Optimove-SDK-Unity

This repository contains 3 folders:
  1. Artifacts has everything necessary to integrate with Optimove Unity SDK. This includes Optimove.unitypackage and OptimoveNativeAssets~ required if integrating with iOS.
  2. unity-sdk contains a Unity project used to create Optimove.unitypackage.
  3. ExampleApp is an example project with imported Optimove.unitypackage. Check ExampleApp/README.md if you want to run it.

For integration:
  1. Import Optimove.unitypackage into your Unity project.
  2. Importing the package will add the OptimoveInit.cs script to the Assets folder. Add it to MainCamera.

Initialization

If you know your credentials when application starts, your initialization should look as follows:

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        let config = OptimoveConfigBuilder(
          optimoveCredentials: "<YOUR_OPTIMOVE_CREDENTIALS>", 
          optimobileCredentials: "<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>")
            .build()

        Optimove.initialize(with: config)
    }
}
public class YourApplication extends Application {

  @Override
  public void onCreate() {
    super.onCreate();

    Optimove.initialize(this, new OptimoveConfig.Builder(
        "<YOUR_OPTIMOVE_CREDENTIALS>", 
        "<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>"
    ).build());
  }
}


/********************** Environments **********************
If you are using staging and prod environments, you will receive 2 different sets of credentials. 
Consider using your BuildConfig file to declare them: */

buildTypes {
        release {
            ...
            buildConfigField "String", "OPTIMOVE_CREDENTIALS", '"<YOUR_OPTIMOVE_CREDENTIALS>"'
            buildConfigField "String", "OPTIMOVE_MOBILE_CREDENTIALS", '"<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>"'
        }
        stg {
            ...
            buildConfigField "String", "OPTIMOVE_CREDENTIALS", '"<YOUR_OPTIMOVE_STAGING_CREDENTIALS>"'
            buildConfigField "String", "OPTIMOVE_MOBILE_CREDENTIALS", '"<YOUR_OPTIMOVE_MOBILE_STAGING_CREDENTIALS>"'
        }
    }
    

// Then initialize Optimove using:

 Optimove.initialize(this, new OptimoveConfig.Builder(
        BuildConfig.OPTIMOVE_CREDENTIALS,
        BuildConfig.OPTIMOVE_MOBILE_CREDENTIALS
    ).build());

/********************** Android **********************

Add the initialization code to your Application extending class onCreate method (usually 
located in android/app/src/main/java/.../MainApplication.java): */

import com.optimove.android.OptimoveConfig;
import com.optimove.reactnative.OptimoveReactNativeConfig;
import com.optimove.reactnative.OptimoveReactNativeInitializer;


OptimoveReactNativeInitializer.initializeOptimove(
    OptimoveReactNativeConfig.newInstance()
                                .optimoveCredentials("<YOUR OPTIMOVE CREDENTIALS>")
                                .optimobileCredentials("<YOUR OPTIMOBILE CREDENTIALS>")
                                .deeplinkEnabled(boolean)
                                // OptimoveConfig.InAppConsentStrategy.EXPLICIT_BY_USER | OptimoveConfig.InAppConsentStrategy.AUTO_ENROLL
                                .enableInAppWithConsentStrategy(OptimoveConfig.InAppConsentStrategy)
                                // Optionally change the notification small icon - .setPushSmallIconId(getApplicationInfo().icon)
                                .build(), getApplicationContext());


/************************ iOS ************************

In your ios/AppDelegate application:didFinishLaunchingWithOptions method */

// For Objective-C: 

#import <OptimoveReactNative/OptimovReactNative-Bridging.h>
...
[OptimoveInitializer initialize:@"<YOUR OPTIMOVE CREDENTIALS>" optimobileCredentials:@"<YOUR OPTIMOBILE CREDENTIALS>" inAppConsentStrategy:@"auto-enroll|in-app-disabled|explicit-by-user" enableDeferredDeepLinking:BOOL];


// For Swift:

import OptimoveReactNative
...
OptimoveInitializer.initialize("<YOUR OPTIMOVE CREDENTIALS>", optimobileCredentials: "<YOUR OPTIMOBILE CREDENTIALS>", inAppConsentStrategy: "auto-enroll|in-app-disabled|explicit-by-user", enableDeferredDeepLinking: Bool)

// 1. Create an optimove.json file in your project's root directory with the following:
{
  "optimoveCredentials": "YOUR_OPTIMOVE_CREDENTIALS",
  "optimobileCredentials": "YOUR_OPTIMOVE_MOBILE_CREDENTIALS",
  "inAppConsentStrategy": "in-app-disabled|auto-enroll|explicit-by-user",
  "enableDeferredDeepLinking": false
}

// 2. Declare the asset in your pubspec.yaml:
assets:
  - optimove.json

// 3. In your Dart code, you can now import and use Optimove features:
import 'package:optimove_sdk_flutter/optimove.dart';
// 1. Create an optimove.json file in your project's root directory with the following content:
{
  "optimoveCredentials": "YOUR_OPTIMOVE_CREDENTIALS",
  "optimoveMobileCredentials": "YOUR_OPTIMOVE_MOBILE_CREDENTIALS",
  "inAppConsentStrategy": "in-app-disabled|auto-enroll|explicit-by-user",
  "enableDeferredDeepLinking": false
}

// 2. After you modify optimove.json, don't forget to run:
cordova prepare <platform>

// 3. Finally, if you are using TypeScript, please add the following to your tsconfig.json:
"files": ["./node_modules/@optimove-inc/cordova-sdk/index.d.ts"] 

/********************** Android **********************

Optimove Cordova SDK requires compileSdkVersion 31. Apps created with Cordova 11 by default 
depend on cordova-android@10.*, which sets the default compileSdkVersion to 30. If you are 
getting related errors, you can: */

// 1. Override compileSdkVersion in config.xml:

<platform name="android">
  <preference name="android-targetSdkVersion" value="31" />
</platform>

// 2. Upgrade the dependency:

cordova platform update [email protected]

/*  Please note that the default Android toolchains have moved to JDK11 now. 
You must use JDK11, at least if you change any of the Android API target versions to >=31.

### Other

(Optional) Optimove SDK includes Firebase Bill of Materials. You may override BoM 
version by adding build-extras.gradle to platforms/android/app with the following content: */

ext {
    // Optimove supports [19.0.0, 22.99.99] Firebase Messaging version range,
    // which corresponds to [20.0.0, 28.99.99] Bill of Materials version range.
    OptimoveFirebaseBoMVersion = "28.2.0"
}

/************************ iOS ************************

After you have added the plugin, run the following commands: */

   cd app/platforms/ios
   pod install
   cordova prepare ios

/* 
After first adding the iOS platform, you may need to open the project in 
Xcode and fix any errors if present.

************** Typescript / Javascript **************

In either case, you don't need to import anything from the plugin module. Types are 
available as ambient declarations. For example, in your www/js/index.js, you can 
use the global Optimove object like this: */

document.addEventListener('deviceready', function () {
    if (typeof Optimove === 'undefined') {
      console.info('Optimove plugin not found');
      return;
    }

    Optimove.setPushReceivedHandler(() => {});
}, false);
// Create Assets/OptimoveConfigFiles/optimove.json file with the following content:

  {
    "optimoveCredentials": "YOUR_OPTIMOVE_CREDENTIALS",
    "optimobileCredentials": "YOUR_OPTIMOVE_MOBILE_CREDENTIALS"
  }

/********************** Android **********************

In Player Settings verify the following (it should be set automatically):
- Custom gradle main template set to Plugins/Android/mainTemplate.gradle
- Custom gradle launcher template set to Plugins/Android/launcherTemplate.gradle
- Custom gradle base template set to Plugins/Android/baseProjectTemplate.gradle
- Custom main manifest set to Plugins/Android/AndroidManifest.xml
- For 2020.3+ make sure the custom gradle properties template is set to Plugins/Android/gradleTemplate.properties

************************ iOS ************************

1. Move Artifacts/OptimoveNativeAssets~ from the Artifacts folder to the Assets/ folder. 
The xcframeworks will be automatically added when the project is built.
2. Build the project. Verify that the New Build System in Xcode is enabled.

*********************** Usage ***********************

In your Unity code, you can now import and use Optimove features: */

using OptimoveSdk;

Delaying the initialization

In rare cases when you determine credentials dynamically, you can use delayed initialization. Currently, only the SDKs listed below support this feature.

let config = OptimoveConfigBuilder(region: .US, features: [.optimove, .optimobile]).build()
Optimove.initialize(with: config)

// time passes...

Optimove.setCredentials(optimoveCredentials: "OPTIMOVE_TOKEN", optimobileCredentials: "OPTIMOBILE_TOKEN")
public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        OptimoveConfig.FeatureSet desiredFeatures = new OptimoveConfig.FeatureSet()
                .withOptimobile()
                .withOptimove();  

        Optimove.initialize(this, new OptimoveConfig.Builder(OptimoveConfig.Region.EU, desiredFeatures).build());
    }
}

// time passes...

Optimove.setCredentials( "<YOUR_OPTIMOVE_CREDENTIALS>", "<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>");

// After credentials are set, all caches are flushed and the SDK starts behaving identical to 
the Standard Initialisation.

You can retrieve the region and feature by contacting an Optimove CSM specialist.

Checking your installs

When you run your app on a simulator or install your app on a device, you can check that the SDK has been initialized correctly by selecting the app and clicking the Installs tab, found under OptiMobile in the Settings area, to see the most recent installs of your app. You should be able to see an install appear at the top of the page.


Push Notifications

Now that you have successfully integrated the SDK, you can add the ability to send push notifications to your customers.

📘

To unlock this capability, you will need to have added Mobile Push Notifications to your Optimove package. If you can’t see this feature in your Optimove instance, contact your CSM to find out more.

📘

Migrating from another third-party vendor

If you are migrating from another third-party vendor, you will need to swap out their SDK for our SDK. You will need to do this to obtain the device token for each customer. However, this will not cause the customer to be asked again to give permission for push notifications. If a customer has already given permission for push notifications, the Optimove SDK will automatically get the device token without asking the user again.

Configure Push Gateways

In order to send messages to users of your app, you must configure one or more messaging gateways, depending on your desired platform. For mobile push notifications, this will likely involve configuring the Apple Push Notification Service (APNS) and/or Firebase Cloud Messaging (FCM) and uploading your push certificates to Optimove.

Optimove UI

To begin configuring gateways, navigate to the Settings area of the site, scroll to OptiMobile, and select Mobile Push Config.

Click the cog icon next to the platform you would like to configure to open the dialog where you can enter the required information to send push notifications to iOS devices via APNS, Android devices via FCM, or Huawei devices via HCM.


APNs Configuration

To send push notifications to iOS devices with Optimove, you have to set up APNs credentials in your Apple Developer account and configure push.

In order to generate a P8 key for Apple services, access your account at https://developer.apple.com/ and select "Certificates, Identifiers & Profiles", then select "Keys" on the left.

Select "Create a Key" and on the form "Register a New Key" enter a meaningful name such as "APNS Access Key" and check the "Enable" checkbox for "Apple Push Notifications service (APNs)", click "Continue".

On the confirmation screen double-check the APNs enablement is set then click "Register".

On the final screen, note your KeyID and download the key. This will save a .p8 file containing the access credentials. Note that the key can only be downloaded once. If lost, it must be revoked and re-created.

You now have all the details to configure your App, so navigate to the Settings area of the site, scroll to OptiMobile, and select Mobile Push Config. Click the cog next to the Apple icon. Select APNs P8 and select your file, enter your other details and click "Configure".


FCM Configuration

In order to enable push notifications for Android with Optimove, you'll need to set up an FCM project and configure push for your app.

Optimove requires a service account to execute campaigns for your FCM project. This service account should contain a custom role with just one permission - cloudmessaging.messages.create (you can read about custom roles here, about this specific permission here)

Please note it is the Google Service Account private key JSON file that needs to be uploaded to your mobile UI, not the Google Services JSON file you include in your app project.

Follow these steps to generate this key:

  1. Go to your Google Cloud Platform console
  2. Navigate to IAM & Admin
  3. Navigate to Roles
  4. Click on "Create Role" at the top
  5. Fill the fields (As a name you can choose something like 'Optimove FCM')
  6. Click on "Add Permissions"
  7. Search for cloudmessaging.messages.create and choose it
  8. Click create
  9. Navigate to Service Accounts
  10. Click on "Create Service Account" at the top
  11. Select the custom role you created in 8
  12. Click done
  13. Click on the service account you generated
  14. Generate a key to this service account

If you have multiple App projects (for example, one for production and one for staging), you must perform this step for each project.

Once you have generated the JSON file, navigate to the Settings area of the site, scroll to OptiMobile, and select Mobile Push Config. Click the cog next to the Android icon. Select your Google Service Account JSON file and click "Configure".

📢

Important

The latest Huawei handsets such as the P40 family of phones do not use FCM for push notifications and instead use Huawei Cloud Messaging (HCM). If you want to message all your Android users, including those using Huawei phones, then in addition to FCM you also need to configure HCM.

HCM Configuration

After completing the FCM configuration, you also need to:

  1. Set up an app on the Huawei Mobile Developer Console
  2. Configure Push in the Mobile Marketing UI
  3. Add Huawei Mobile Services dependencies, files, and plugins to your project
  4. Add Huawei-specific manifest entries

All other push behavior & customization works identically to FCM.

To begin, configure a project on the Huawei Developer Console, and enable the Push feature by following the Push Kit developer guide step 1.

Note that your app needs a valid signing configuration for both debug and release builds. The SHA-256 fingerprint of your signing key is required to match the Huawei app configuration prior to continuing.

Once you have created the app, configure the HCM gateway in Optimove. Navigate to the Settings area of the site, scroll to OptiMobile, and select Mobile Push Config. Click the cog next to the Huawei icon. Add your App ID and App Secret and click "Configure".

App Setup

Once you've configured the Mobile Push Gateways and the appropriate push notification setup for your platform, follow the SDK integration steps below.

In your app project settings use the "+ capability" button to add the Background 
Modes and Push Notifications capabilities, in Background Modes you should have 
the "Remote Notifications" mode checked.

Note: you must use a real device to test push notifications on iOS because simulators cannot 
register for push notifications.
/*
1. Preliminary Setup:

   - Ensure you've added the necessary Firebase components to your app.
   - For more information, visit: https://firebase.google.com/docs/android/setup.

2. Edit the build.gradle Files:

   - In your root build.gradle file, ensure the Google repository is enabled and the 
   google-services plugin is on the classpath: */
   
     buildscript {
         // ...
         dependencies {
             // ...
             classpath 'com.google.gms:google-services:4.3.10' // google-services plugin
         }
     }

     allprojects {
         // ...
         repositories {
             google() // Google's Maven repository
             // ...
         }
     }

/*
   - In your app module's build.gradle file, add the FCM dependency and apply the  google-services 
   plugin. Note: Optimove supports Firebase Messaging version range [19.0.0, 22.99.99], which 
   corresponds to Bill of Materials version range [20.0.0, 28.99.99]. */

     apply plugin: 'com.android.application'

     dependencies {
         ...
         implementation 'com.optimove.android:optimove-android:7.+'
         // Add library dependency to retrieve FCM push tokens
         implementation platform('com.google.firebase:firebase-bom:28.2.0')
         implementation 'com.google.firebase:firebase-messaging'
     }

     // ADD THIS AT THE BOTTOM
     apply plugin: 'com.google.gms.google-services'

/*
3. Add google-services.json:

   - Download the google-services.json file from your Firebase app's 'General' settings.
   - Add this file to your app/ folder.

4. Update AndroidManifest.xml:

   - Add the OptimoveFirebaseMessagingService and PushBroadcastReceiver to your 
   AndroidManifest.xml file: */

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

         <!-- Optionally add the wake lock permission to stop the CPU from sleeping when a message is received -->
         <!-- <uses-permission android:name="android.permission.WAKE_LOCK" /> -->
         <!-- Optionally add the boot completed permission to allow periodic tasks to persist across phone reboots -->
         <!-- <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> -->

         <application
             android:name=".ExampleApp"
             android:allowBackup="true"
             android:icon="@mipmap/ic_launcher"
             android:label="@string/app_name"
             android:supportsRtl="true"
             android:theme="@style/AppTheme">

             <!-- Other application components -->

             <!-- Optimove FCM handler -->
             <service android:name="com.optimove.android.optimobile.FirebaseMessagingService" android:exported="false">
                 <intent-filter>
                     <action android:name="com.google.firebase.MESSAGING_EVENT" />
                 </intent-filter>
             </service>

             <!-- Optimove Push receiver -->
             <receiver android:name="com.optimove.android.optimobile.PushBroadcastReceiver" android:exported="false">
                 <intent-filter>
                     <action android:name="com.optimove.push.RECEIVED" />
                     <action android:name="com.optimove.push.OPENED" />
                     <action android:name="com.optimove.push.DISMISSED" />
                     <action android:name="com.optimove.push.BUTTON_CLICKED" />
                 </intent-filter>
             </receiver>
         </application>
     </manifest>
     
/********************** Huawei **********************

1. Add the agconnect-services.json file (downloaded from the Huawei developer console) to 
ndroid application directory.

2. Add the Huawei repository and plugin dependency to your root build.gradle: */

buildscript {
    repositories {
        ...
        maven {
            url 'https://developer.huawei.com/repo/'
        }
    }
    dependencies {
        ...
        classpath 'com.huawei.agconnect:agcp:1.2.1.301'
    }
}

allprojects {
    repositories {
        ...
        maven {
            url 'http://developer.huawei.com/repo/'
        }
    }
}

/*
3. In your app-level build.gradle, add the HMS Push Kit dependency and apply the HMS plugin: */

dependencies {
    ...
    implementation 'com.huawei.hms:push:6.1.0.300'
}

// Add to bottom of file
apply plugin: 'com.huawei.agconnect'

/*
4. Add the HMS push service to your AndroidManifest.xml: */

<!-- Optimove HMS Messaging Service -->
<service
    android:name="com.optimove.android.optimobile.HmsMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
    </intent-filter>
</service>

/*
5. Push registration should be performed as with FCM. //HELP By this do we mean allowing push notificaitons?

6. Huawei Troubleshooting
 -  Ensure the app signing key fingerprint matches in the Huawei developer console
 -  Ensure the app package matches the configuration in the Huawei developer console
 -  Ensure the Push Kit service is enabled for your app in AppGallery Connect > App > Develop > Grow > Push Kit. You must enable the service and choose a data storage location.
*/

/********************** Android **********************

1. Preliminary Setup:

   - Ensure you've added the necessary Firebase components to your app.
   - For more information, visit: https://firebase.google.com/docs/android/setup.

2. Edit the build.gradle Files:

   - In your root build.gradle file, ensure the Google repository is enabled and the 
   google-services plugin is on the classpath: */
   
     buildscript {
         // ...
         dependencies {
             // ...
             classpath 'com.google.gms:google-services:4.3.10' // google-services plugin
         }
     }

     allprojects {
         // ...
         repositories {
             google() // Google's Maven repository
             // ...
         }
     }

/*
   - In your app module's build.gradle file, add the FCM dependency and apply the  google-services 
   plugin. Note: Optimove supports Firebase Messaging version range [19.0.0, 22.99.99], which 
   corresponds to Bill of Materials version range [20.0.0, 28.99.99]. */

     apply plugin: 'com.android.application'

     dependencies {
         ...
         implementation 'com.optimove.android:optimove-android:7.+'
         // Add library dependency to retrieve FCM push tokens
         implementation platform('com.google.firebase:firebase-bom:28.2.0')
         implementation 'com.google.firebase:firebase-messaging'
     }

     // ADD THIS AT THE BOTTOM
     apply plugin: 'com.google.gms.google-services'

/************************ iOS ************************

In your app project settings use the "+ capability" button to add the Background 
Modes and Push Notifications capabilities, in Background Modes you should have 
the "Remote Notifications" mode checked.

Note: you must use a real device to test push notifications on iOS because simulators cannot 
register for push notifications. */
/********************** Android **********************

1. Preliminary Setup:

   - Ensure you've added the necessary Firebase components to your app.
   - For more information, visit: https://firebase.google.com/docs/android/setup.

2. Edit the build.gradle Files:

   - In your root build.gradle file, ensure the Google repository is enabled and the 
   google-services plugin is on the classpath: */
   
     buildscript {
         // ...
         dependencies {
             // ...
             classpath 'com.google.gms:google-services:4.3.10' // google-services plugin
         }
     }

     allprojects {
         // ...
         repositories {
             google() // Google's Maven repository
             // ...
         }
     }

/*
   - In your app module's build.gradle file, add the FCM dependency and apply the  google-services 
   plugin. Note: Optimove supports Firebase Messaging version range [19.0.0, 22.99.99], which 
   corresponds to Bill of Materials version range [20.0.0, 28.99.99]. */

     apply plugin: 'com.android.application'

     dependencies {
         ...
         implementation 'com.optimove.android:optimove-android:7.+'
         // Add library dependency to retrieve FCM push tokens
         implementation platform('com.google.firebase:firebase-bom:28.2.0')
         implementation 'com.google.firebase:firebase-messaging'
     }

     // ADD THIS AT THE BOTTOM
     apply plugin: 'com.google.gms.google-services'

/************************ iOS ************************

In your app project settings use the "+ capability" button to add the Background 
Modes and Push Notifications capabilities, in Background Modes you should have 
the "Remote Notifications" mode checked.

Note: you must use a real device to test push notifications on iOS because simulators cannot 
register for push notifications.
********************** Android **********************

1. Add google-services.json file from your Firebase app 'General' settings to the root of your 
Cordova project.

2. run: cordova prepare android

************************ iOS ************************

In your app project settings use the "+ capability" button to add the Background Modes 
and Push Notifications capabilities, in Background Modes you should have the 
"Remote Notifications" mode checked.

Note: you must use a real device to test push notifications on iOS because 
simulators cannot register for push notifications.
/********************** Android **********************

Add the google-services.json file from your Firebase app 'General' settings to the 
/Assets/OptimoveConfigFiles folder of your Unity project.

In the /Assets/Plugins/Android/baseProjectTemplate.gradle file, uncomment the following line: */

classpath 'com.google.gms:google-services:4.3.14'

/*
In the /Assets/Plugins/Android/launcherTemplate.gradle file, uncomment the following lines: */

implementation platform('com.google.firebase:firebase-bom:28.2.0')
implementation 'com.google.firebase:firebase-messaging'
...
apply plugin: 'com.google.gms.google-services'

/************************ iOS ************************

No additional steps needed.

Allow push notifications

When you consider it appropriate, you need to request permission from the user to send them push notifications. You can potentially use an in-app message to prompt the user to accept push at a later time.

Whilst you can handle this yourself, Optimove provides a convenience method. When the user accepts, the Optimove SDK will store the push token.

Optimove.shared.pushRequestDeviceToken()  
Optimove.getInstance().pushRequestDeviceToken(); // Starting from Android 13, this method will open the notification permission request prompt 
Optimove.pushRequestDeviceToken();
Optimove.pushRequestDeviceToken();
Optimove.pushRequestDeviceToken();
Optimove.Shared.PushRegister();

Make sure to provide your OptiMobile credentials during the initialization, as they are necessary for Push Messaging.

Send Test Push

After allowing push notifications on the device, go to the Installs tab, found under OptiMobile in the Settings area. You will notice that the install is now registered for push. Click on an install, click the Push tab, and click Send Test Push.

If you do not receive the push notification, check the Error Log for any errors sending the push notification to the native push gateways. If you continue to experience problems, please contact your CSM for support in troubleshooting the configuration.

Opt-outs

If at a later stage the user wishes to opt out from push notifications without blocking them via the Notification Center Optimove provides a convenience method. This will mark the token as soft-deleted in Optimove to allow for easy re-enabling later.

Optimove.shared.pushUnregister()
Optimove.getInstance().pushUnregister();
Optimove.pushUnregister();
Optimove.pushUnregister();
Optimove.pushUnregister();
Optimove.Shared.PushUnregister();

Reviewing Your Configuration

To review your messaging gateway configuration, Navigate to the Settings area of the site, scroll to OptiMobile, and select Mobile Push Config. This will show how many installs are subscribed to receive push notifications and how many users have opted in to receive in-app messages, broken down by platform.


What’s Next

With the SDK now set up, you can explore our SDK reference for a complete list of features and review our testing and troubleshooting guide.