flutter_aepcore 5.0.0

Official Adobe Experience Platform support for Flutter apps. The Mobile Core represents the core Adobe Experience Platform SDK that is required for every app implementation.

flutter_aepcore

flutter_aepcore is a flutter plugin for the iOS and Android AEP Core SDK to allow for integration with flutter applications. Functionality to enable the Core extension is provided entirely through Dart documented below.

Contents

• Installation
• Importing the plugins
• Initializing
• Core
• Identity
• Lifecycle
• Signal
• Tests

Installation

Install instructions for this package can be found here.

Note: After you have installed the SDK, don't forget to run pod install in your ios directory to link the libraries to your Xcode project.

Importing the Plugins

Import the package in your Dart code as follows:

import 'package:flutter_{extension}/flutter_{plugin_name}.dart'

Initializing

To initialize the SDK, use the following methods:

• MobileCore.initializeWithAppId(appId)
• MobileCore.initialize(initOptions)

Refer to the root Readme for more information about the SDK setup.

Core

For more detailed information on the Core APIs, visit the documentation here

Importing Core:

In your Flutter application, import the Core package as follows:

import 'package:flutter_aepcore/flutter_aepcore.dart';

API reference

extensionVersion

Returns the SDK version of the Core extension.

Syntax

Future<String> get extensionVersion

Example

String version = await MobileCore.extensionVersion;

initializeWithAppId

Initialize the AEP SDK by automatically registering all extensions bundled with the application and enabling automatic lifecycle tracking.

appId: Configures the SDK with the provided mobile property environment ID configured from the Data Collection UI.

Syntax

static Future<void> initializeWithAppId({required String appId})

Example

class _HomePageState extends State<HomePage> {
  /// Initialize the Adobe Experience Platform Mobile SDK inside the initState method.
  @override
  void initState() {
    super.initState();
    _initializeAEPMobileSdk();
  }

 Future<void> _initializeAEPMobileSdk() async {
    MobileCore.setLogLevel(LogLevel.trace);
    MobileCore.initializeWithAppId(appId:"YOUR_APP_ID");
  }
}

Note

Starting from Adobe Experience Platform Flutter 5.x, there is no longer a need to initialize the SDK on the native platforms, as was required in earlier versions.

initialize

Initialize the AEP SDK by automatically registering all extensions bundled with the application and enabling automatic lifecycle tracking. This API also allows further customization by accepting InitOptions.

InitOptions: Allow customization of the default initialization behavior. Refer to the InitOptions.

Syntax

static Future<void> initialize({required InitOptions initOptions}) 

Example

class _HomePageState extends State<HomePage> {
  /// Initialize the Adobe Experience Platform Mobile SDK inside the initState method.
  @override
  void initState() {
    super.initState();
    _initializeAEPMobileSdk();
  }

  Future<void> _initializeAEPMobileSdk() async {
    MobileCore.setLogLevel(LogLevel.trace);
    
    try {
      InitOptions initOptions = InitOptions(
      appId: "YOUR-APP-ID", 
      lifecycleAutomaticTrackingEnabled: true,
      lifecycleAdditionalContextData: {"key": "value"}
      );

      MobileCore.initialize(initOptions: initOptions);
      print("Adobe Experience Platform Mobile SDK was initialized");
    } catch (e) {
      print("Failed to initialize Adobe Experience Platform Mobile SDK: $e");
    }
  }
}

InitOptions

The InitOptions class defines the options for initializing the AEP SDK. It currently supports the following options:

• appID – The App ID used to retrieve remote configurations from Adobe servers.
• lifecycleAutomaticTrackingEnabled – A boolean flag to enable or disable automatic lifecycle tracking
• lifecycleAdditionalContextData – A map containing extra context data to be sent with the lifecycle start event.
• appGroup (iOS only) – A string representing the App Group identifier for sharing data between app extensions and the main application.

updateConfiguration

Update the configuration programmatically by passing configuration keys and values to override the existing configuration.

Syntax

static Future<void> updateConfiguration(Map<String, Object> configMap)

Example

MobileCore.updateConfiguration({"key" : "value"});

clearUpdatedConfiguration

Clearing configuration updates back to original configuration.

Syntax

static Future<void> clearUpdatedConfiguration()

Example

MobileCore.clearUpdatedConfiguration();

setLogLevel

Control the log level of the SDK.

Syntax

static Future<void> setLogLevel(LogLevel mode)

Example

MobileCore.setLogLevel(LogLevel.error);
MobileCore.setLogLevel(LogLevel.warning);
MobileCore.setLogLevel(LogLevel.debug);
MobileCore.setLogLevel(LogLevel.trace);

get privacyStatus

Get the current privacy status.

Syntax

static Future<PrivacyStatus> get privacyStatus

Example

PrivacyStatus result;

try {
  result = await MobileCore.privacyStatus;
} on PlatformException {
  log("Failed to get privacy status");
}

setPrivacyStatus

Set the privacy status.

Syntax

static Future<void> setPrivacyStatus(PrivacyStatus privacyStatus)

Example

MobileCore.setPrivacyStatus(PrivacyStatus.opt_in);
MobileCore.setPrivacyStatus(PrivacyStatus.opt_out);
MobileCore.setPrivacyStatus(PrivacyStatus.unknown);

get sdkIdentities

Get the SDK identities.

Syntax

static Future<String> get sdkIdentities

Example

String result = "";

try {
  result = await MobileCore.sdkIdentities;
} on PlatformException {
  log("Failed to get sdk identities");
}

dispatchEvent

Dispatch an Event Hub event.

Syntax

static Future<void> dispatchEvent(Event event)

Example

final Event event = Event({
  "eventName": "testEventName",
  "eventType": "testEventType",
  "eventSource": "testEventSource",
  "eventData": {"eventDataKey": "eventDataValue"}
});
try {
  await MobileCore.dispatchEvent(event);
} on PlatformException catch (e) {
  log("Failed to dispatch event '${e.message}''");
}

dispatchEventWithResponseCallback

Dispatch an Event Hub event with callback.

Syntax

static Future<Event> dispatchEventWithResponseCallback

Example

Event result;
final Event event = Event({
      "eventName": "testEventName",
      "eventType": "testEventType",
      "eventSource": "testEventSource",
      "eventData": {"eventDataKey": "eventDataValue"}
    });
    try {
      result = await MobileCore.dispatchEventWithResponseCallback(event, 1000);
    } on PlatformException catch (e) {
      log("Failed to dispatch event '${e.message}''");
    }

resetIdentities

The resetIdentities method requests that each extension resets the identities it owns and each extension responds to this request uniquely.

Syntax

static Future<void> resetIdentities()

Example

MobileCore.resetIdentities()

trackAction

Track event actions that occur in your application.

Important

trackAction is supported through Edge Bridge and Edge Network extensions.

Syntax

static Future<void> trackAction

Example

MobileCore.trackAction("myAction",  data: {"key1": "value1"});

trackState

Track states that represent screens or views in your application.

Important

trackState is supported through Edge Bridge and Edge Network extensions.

Syntax

static Future<void> trackState

Example

MobileCore.trackState("myState",  data: {"key1": "value1"});

Identity

For more information on the Core Identity APIs, visit the documentation here.

Importing Identity:

In your Flutter application, import the Identity package as follows:

import 'package:flutter_aepcore/flutter_aepidentity.dart';

API reference

extensionVersion

Returns the SDK version of the Identity extension.

Syntax

Future<String> get extensionVersion

Example

String version = await Identity.extensionVersion;

syncIdentifier

Updates the given customer ID with the Adobe Experience Cloud ID Service.

Syntax

static Future<void> syncIdentifier

Example

Identity.syncIdentifier("identifierType", "identifier", MobileVisitorAuthenticationState.authenticated);

syncIdentifiers

Updates the given customer IDs with the Adobe Experience Cloud ID Service.

Syntax

static Future<void> syncIdentifiers(Map<String, String> identifiers)

Example

Identity.syncIdentifiers({"idType1":"idValue1",
                                    "idType2":"idValue2",
                                    "idType3":"idValue3"});

syncIdentifiersWithAuthState

Updates the given customer IDs with Authentication State using the Adobe Experience Cloud ID Service.

Syntax

static Future<void> syncIdentifiersWithAuthState

Example

Identity.syncIdentifiersWithAuthState({"idType1":"idValue1", "idType2":"idValue2", "idType3":"idValue3"}, MobileVisitorAuthenticationState.authenticated);

Note: MobileVisitorAuthenticationState is defined as:

enum MobileVisitorAuthenticationState {unknown, authenticated, logged_out}

appendToUrl

Append visitor data to a URL.

Syntax

static Future<String> appendToUrl(String url)

Example

String result = "";

try {
  result = await Identity.appendToUrl("www.myUrl.com");
} on PlatformException {
  log("Failed to append URL");
}

get urlVariables

Get visitor data as URL query parameter string.

Syntax

static Future<String> get urlVariables

Example

String result = "";

try {
  result = await Identity.urlVariables;
} on PlatformException {
  log("Failed to get url variables");
}

get identifiers

Returns all customer identifiers that were previously synced with the Adobe Experience Cloud.

Syntax

static Future<List<Identifiable>> get identifiers

Example

List<Identifiable> result;

try {
  result = await Identity.identifiers;
} on PlatformException {
  log("Failed to get identifiers");
}

getExperienceCloudId

This API retrieves the Experience Cloud ID (ECID) that was generated when the app was initially launched. This ID is preserved between app upgrades, is saved and restored during the standard application backup process, and is removed at uninstall.

Syntax

static Future<String> get experienceCloudId

Example

String result = "";

try {
  result = await Identity.experienceCloudId;
} on PlatformException {
  log("Failed to get experienceCloudId");
}

Lifecycle

For more information about Lifecycle for Edge Network, visit the documentation here.

Starting from Adobe Experience Platform Flutter 5.x, lifecycle tracking is enabled automatically with Initialize APIs by default.

Refer to

• MobileCore.initializeWithAppId(appId)
• MobileCore.initialize(initOptions)

Signal

For more information on the Core Signal APIs, visit the documentation here

Importing Signal:

In your Flutter application, import the Signal package as follows:

import 'package:flutter_aepcore/flutter_aepsignal.dart';

API reference

extensionVersion

Returns the SDK version of the Core extension.

Syntax

static Future<String> get extensionVersion

Example

String version = await Signal.extensionVersion;

Tests

Run:

$ cd plugins/flutter_{plugin_name}/
$ flutter test

Contributing

See CONTRIBUTING

License

See LICENSE