Flutter

Things to keep handy before starting your integration with Apxor

Please have the following handy before beginning the integration:

• Application identifier generated on the Apxor dashboard for your app (Read more on how to fetch the application identifier from Apxor dashboard)

• App Bundle Id : Every app has a unique application ID that looks like com.example.myapp. This id uniquely identifies the app on the device and also on the app store. (Know more about bundle ids here)

• The list of events to setup triggers and track goals, user properties that allows to personalize messages and to target better. (Read more on how you can setup here)

Getting Started

Prerequisites

Flutter SDK supported version is >= 3.0.1.

Set TAGs for Widgets

In order to display actions on Widgets, you can set tags for widgets using ValueKey with String as a value to it. It is highly recommended to set TAGs for Widgets which are Scrollable or contains multiple child widgets.

return TextButton(
  child: const Text('Sign In'),
  key: const ValueKey("Sign-in"), // Add ValueKey with String
  onPressed: () {
    // Sign in
  },
);

Flutter Integration

Step 1: Add Apxor SDK

Add apxor_flutter dependency in pubspec.yaml

dependencies:
  apxor_flutter:
    git: https://github.com/apxor/apxor-flutter-sdk.git

Step 2: Wrap Main Widget with Apxor Wrapper

import 'package:apxor_flutter/apxor.dart';
import 'package:apxor_flutter/observer.dart';
@override
  Widget build(BuildContext context) {
	return ApxorFlutter.createWidget(MaterialApp(
              	…
        ),
);
}

Step 3: Tracking Screens

If you are using Navigator in your Application

return Navigator(
      observers: [ApxNavigationObserver()],
      …
      );

You are not using Navigator in your Application

add ApxNavigationObserver wherever routes are defined

@override
  Widget build(BuildContext context) {
    return ApxorFlutter.createWidget(
      MaterialApp(
        navigatorObservers: [ApxNavigationObserver()],
	  routes: {
		…
		}
	  …
	),
    )
 }

Passing Context for screen

To avoid getting the elements from previous screens add the following in build method

Widget build(BuildContext context) {
    ApxorFlutter.setContext("{Enter you route name here}", context);
}

Step 4: Handle deeplink redirection

Use setDeeplinkListener to listen on deeplink redirection from Apxor SDK and handle redirection logic (including external redirection) within application logic as follows

ApxorFlutter.setDeeplinkListener((url) {
  // interpret the URL and handle redirection within the application
  _routeState.go(url!);

  // Or, to an external URL which will be opened in Browser
});

Android Integration

Step 0: Add Apxor Repository

Add Maven URL in project level build.gradle file.

Path: <project>/android/build.gradle:

allprojects {
    repositories {
        // ...
        maven {
           url "https://repo.apxor.com/artifactory/list/libs-release-android/"
        }
        // ...
    }
}

Step 1: Add Dependencies to your build.gradle file

Path: <project>/android/app/build.gradle:

dependencies {
  // Core plugin tracks events & manages the session
  implementation "com.apxor.androidx:apxor-android-sdk-core:3.2.2@aar"

  // Context Evaluation plugin
  implementation "com.apxor.androidx:apxor-android-sdk-qe:1.8.6@aar"

  // Real time messaging plugin to display Tooltips, Coachmarks, InApps and Onboarding walkthroughs
  implementation "com.apxor.androidx:apxor-android-sdk-rtm:2.6.6@aar"

  // Display contextual surveys (both are mandatory)
  implementation "com.apxor.androidx:surveys:2.2.7@aar"
  implementation 'androidx.viewpager2:viewpager2:1.0.0'

  // Helper plugin for RTM plugin to pick the PATH for any view
  implementation "com.apxor.androidx:wysiwyg:1.6.3@aar"
  
  // Add the below two dependencies to establish SSE connection for WYSIWYG
    implementation 'com.squareup.okhttp3:okhttp:4.9.0'
    implementation 'com.launchdarkly:okhttp-eventsource:2.5.0'
}

Step 2: Plugins Integration

Create plugins.json file in assets folder.

Path: android/app/src/main/assets/plugins.json

{
  "plugins": [
    {
      "name": "rtm",
      "class": "com.apxor.androidsdk.plugins.realtimeui.ApxorRealtimeUIPlugin"
    },
    {
      "name": "push-v2",
      "class": "com.apxor.androidsdk.plugins.push.v2.PushPlugin"
    },
    {
      "name": "wysiwyg",
      "class": "com.apxor.androidsdk.plugins.wysiwyg.WYSIWYGPlugin"
    },
    {
      "name": "surveys",
      "class": "com.apxor.androidsdk.plugins.survey.SurveyPlugin"
    },
  ]
}

Step 3: Initialize ApxorSDK

Add meta-data tag in AndroidManifest.xml file with your unique APP_ID as a value. You need to replace YOUR_APP_ID with your actual App Id. Click here to know how to get app-id.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.apxor.flutter_example">
  <application ...>
      <meta-data android:name="APXOR_APP_ID" android:value="YOUR_APP_ID" />
    </application>
</manifest>

Step 4: Add Proguard Rules

Note

This is a mandatory step

If you do not have a proguard-rules.pro file in android folder then create one and configure the below rules in that proguard-rules.pro file. If you already have a proguard-rules.pro file in android folder then just configure the below rules in the existing file.

-keep class com.apxor.** { *; }
-dontwarn com.apxor.**

Add the following in <project>/android/app/build.gradle

buildTypes {
       release {
           signingConfig signingConfigs.release
           proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
       }
   }

Step 5: Add exoplayer in your app (optional)

Exoplayer enables to configure Picture In Picture videos from Apxor dashboard and typically increases the app size by ~1Mb, if you are already using exoplayer in your app this step is not needed else add the following dependency in the application build.gradle file

Path: <project>/<app-module>/build.gradle:

com.apxor.androidx:apxor-android-sdk-rtm:2.3.6@aar version onwards

Copy

dependendies {
  //... 

  implementation 'androidx.media3:media3-exoplayer:1.1.1'
  implementation 'androidx.media3:media3-ui:1.1.1'


  //...
  }

com.apxor.androidx:apxor-android-sdk-rtm:2.3.5@aar and below

Copy

dependendies {
  //... 

  implementation 'com.google.android.exoplayer:exoplayer:2.14.0'

  //...
  }

Step 6: Disable Dexing Artifact Transformation [optional]

This step is needed only if you use Apxor's Video InApp messages.

Note

In the Android Gradle Plugin 3.5.0, we desugar & dex using Gradle artifact tranforms, which allow more parallelism and caching. This mechanism relies on libraries having the correct Maven information, because we use dependencies specified in POM files to set up the desugaring classpath. In cases we are unable to see all dependencies when desugaring a class it is required to disable parallel transformation to faciliate the process by adding the property as mentioned below.

Add the following in gradle.properties

Path: <project>/<app-module>/gradle.properties:

android.enableDexingArtifactTransform = false

Step 7: Ensuring ApxorSDK is initialised successfully

We have to verify for two things as follows :

SDK Initialisation

On running your android project lookout for the following log in logcat :

ApxorSDK(v2**) successfully initialized for: APP_ID

Plugin Initialisation

By default, only error logs are enabled. To see debug logs for plugin initialisation and to confirm tracking event triggers, user properties. Please run the below command in terminal

adb shell setprop log.tag.Apxor VERBOSE

Note

Apxor uploads data only when the app is minimized to the background. If you are running from Android Studio (emulators or devices), do not stop the app, just press on the "home" button in order for data to be uploaded.

Step 8: Log data to set up triggers and measure goals

Now as we are done with basic integration, we can go ahead to setup event triggers, capture data for targeting and to personalize messaging.

Click here for guides to log user properties, events and event properties.

iOS Integration

Step 1: Auto initialize SDK

To Auto initialize SDK (Recommended), add the following inside your application plist file.

Open your application's Info.plist as source code.Open Plist as Source Code

Copy paste the below piece of code, to create an entry for ApxorSDK.

<key>Apxor</key>
<dict>
    <key>Core</key>
    <string>YOUR_APP_ID</string>
    <key>APXSurveyPlugin</key>
    <true/>
    <key>APXRTAPlugin</key>
    <true/>
    <key>APXPushPlugin</key>
    <true/>
    <key>APXWYSIWYGPlugin</key>
    <true/>
</dict>

Note

• If you are unable to find our plugins in your pods after flutter run, then dopod update

Step 2: Configuring Test Device

You need to configure your app to ensure there is a URL Scheme with your application's bundle identifier as the value.

If your app already has a URL Scheme with your application's bundle identifier as the value, you can skip this step.

Configuring URL Scheme

To configure URL scheme:

1. go to your project settings

2. select Targets

3. Click on the Info tab

4. Select the URL Types, and click on the + button to add a new URL Scheme

5. Add a new URL Scheme with your bundle identifier as the value

Note

Make sure the URL scheme has the value of your bundle identifier that was provided in the dashboard while registering with us. Also, the app must have the same bundle identifier.

Step 3: Handling the deep link

Enable Apxor to handle Apxor specific deeplinks.

In your application's AppDelegate file, in the function application(_:open:options:), add the following code at the beginning,

// ObjC
NSString *urlStr = url.absoluteString;
if ([urlStr containsString:@"add-test-device"]) {
  [ApxorSDK handleDeeplink:url];
}

// Swift
let urlStr = url.absoluteString
if (urlStr.contains("add-test-device")) {
    ApxorSDK.handleDeeplink(url)
}

Step 4: Log data to set up triggers and measure goals

Now as we are done with basic integration, we can go ahead to setup event triggers, capture data for targeting and to personalize messaging.

Click here for guides to log user properties, events and event properties.

Embed Slot

Note

For using Apxor Embedded Cards the versions of the following plugins should be greater than or equal the ones mentioned below

Core: 2.10.26

RTA: 1.09.26

CE: 1.05.16

WYSIWYG: 1.02.67

In all areas of the app where you may want to show an in-line widget, insert the following code

const ApxorEmbedWidget(valueKey: <Tag>)

Rename <Tag> to any unique ID (any positive Integer). Ensure that you keep the ID unique across different IDs and across different ApxorEmbedWidget instances.

Story Slot

Note

For using Apxor Stories the versions of the following plugins should be greater than or equal the ones mentioned below

Core: 2.10.26

RTA: 1.09.26

CE: 1.05.16

WYSIWYG: 1.02.67

In all areas of the app where you may want to show stories, insert the following code

const ApxorStoryWidget(id: <ID>)

Replace <ID> with any unique integer(any positive Integer). Ensure that you keep the ID unique across different ApxorStoryWidget instances.

Web Integration

Step 1: Add integration scripts and Initialize Apxor

Add the following integration scripts to your index.html file in the head tag(project/web/index.html)

Add your site ID and app version in the code below

<!-- Start of Integrating APXOR Web SDK -->

<!-- Initializing Apxor Core -->
<script type="text/javascript" defer src="https://unpkg.com/apxor"></script>

<!-- Initializing Apxor QE -->
<script
  type="text/javascript"
  defer
  src="https://unpkg.com/apxor-qe"
> 
</script>
<!-- Initializing Apxor RTM -->
<script
  type="text/javascript"
  defer
  src="https://unpkg.com/apxor-rtm"
>
</script>

<!-- Initialization step -->
<script>
 
  const _d = new Date();
  (function (a, p, x, o, r) {
    Apxor = a.Apxor || { _q: [], _st: _d };
    [
      "init",
      "setUserId",
      "setUserProperties",
      "setSessionProperties",
      "logPageView",
      "logEvent",
      "logClientEvent",
      "setAppVersion",
      "getClientId",
      "getSessionId",
      "startNewSession",
      "endSession",
      "flattenJSON",
      "setRedirectionHandler",
      "setIsFlutter",
      "registerApxorFlutterHelper",
      "setWYSIWYGCookieForFlutter"
    ].forEach(function (m) {
      Apxor[m] = function () {
        this._q.push({ m: m, args: arguments });
      };
    });
   })(window, document, "script");
   
   Apxor.init(
      "YOUR_SITE_ID",
      {
        idle_time_out: 1800,
        plugins: ["ApxorRTM"],
        Version: <Your_App_Version>,
      },
      
      function success(data) {
        console.log("APXOR SDK Initialized");
      },
      function error() {
        console.log("APXOR SDK not initialized");
      });
      
</script>