@adobe/react-native-aepedge

React Native Adobe Experience Platform Edge Network extension

@adobe/react-native-aepedge is a wrapper around the iOS and Android Adobe Experience Platform Edge Network to allow for integration with React Native applications.

Prerequisites

The Edge Network extension has the following peer dependencies, which must be installed prior to installing the Edge extension:

• Core
• Identity for Edge Network

Installation

See Requirements and Installation instructions on the main page

Install the @adobe/react-native-aepedge package:

cd MyReactApp
npm install @adobe/react-native-aepedge

Usage

Installing and registering the extension with the AEP Mobile Core

Install the Adobe Experience Platform Edge Network extension in your mobile property and configure the default Datastream ID by following the steps in the Edge Network extension documentation.

Then follow the same document for registering the Edge extension with the Mobile Core. Note that initializing the SDK should be done in native code, additional documentation on how to initialize the SDK can be found here.

Initialization Example

iOS

// AppDelegate.h
@import AEPCore;
@import AEPEdge;
@import AEPEdgeIdentity;
...
@implementation AppDelegate

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

   // TODO: Set up the preferred Environment File ID from your mobile property configured in Data Collection UI
   NSString* ENVIRONMENT_FILE_ID = @"YOUR-APP-ID";

   NSArray *extensionsToRegister = @[AEPMobileEdgeIdentity.class, 
                                     AEPMobileEdge.class
                                     ];

  [AEPMobileCore registerExtensions:extensionsToRegister completion:^{
    [AEPMobileCore configureWithAppId: ENVIRONMENT_FILE_ID];  
    ...   
  }]; 
  return YES;   
 } 

@end

Android

import com.adobe.marketing.mobile.MobileCore;
import com.adobe.marketing.mobile.Edge;
import com.adobe.marketing.mobile.edge.identity.Identity;

...
import android.app.Application;
...
public class MainApplication extends Application implements ReactApplication {
  ...
  // TODO: Set up the preferred Environment File ID from your mobile property configured in Data Collection UI
  private final String ENVIRONMENT_FILE_ID = "YOUR-APP-ID";

  @Override
  public void on Create(){
    super.onCreate();
    ...
  
    MobileCore.setApplication(this);
    MobileCore.configureWithAppID(ENVIRONMENT_FILE_ID);

    MobileCore.registerExtensions(
      Arrays.asList(Identity.EXTENSION, Edge.EXTENSION),
      o -> Log.d("MainApp", "Adobe Experience Platform Mobile SDK was initialized")
    );
  }
}  

Importing the extension

In your React Native application, import the Edge extension as follows:

import {Edge, ExperienceEvent} from '@adobe/react-native-aepedge';

API reference

extensionVersion

Returns the version of the client-side Edge extension.

Syntax

extensionVersion(): Promise<string>

Example

Edge.extensionVersion().then(version => console.log("AdobeExperienceSDK: Edge version: " + version));

getLocationHint

Gets the Edge Network location hint used in requests to the Adobe Experience Platform Edge Network. The Edge Network location hint may be used when building the URL for Adobe Experience Platform Edge Network requests to hint at the server cluster to use.

Syntax

getLocationHint(): Promise<string|null>

Example

Edge.getLocationHint().then(hint =>
    console.log('AdobeExperienceSDK: location hint = ' + hint),
);

setLocationHint

Sets the Edge Network location hint used in requests to the Adobe Experience Platform Edge Network. Passing null or an empty string clears the existing location hint. Edge Network responses may overwrite the location hint to a new value when necessary to manage network traffic.

Warning: Use caution when setting the location hint. Only use location hints for the "EdgeNetwork" scope. An incorrect location hint value will cause all Edge Network requests to fail with 404 response code.

Syntax

setLocationHint(hint?: string)

Example

Edge.setLocationHint('va6');

resetIdentity

Resets current state of the AEP Edge extension and clears previously cached content related to current identity, if any. See MobileCore.resetIdentities for more details.

sendEvent

Sends an Experience event to Edge Network.

Starting with @adobe/react-native-aepedge v5.1.0, the sendEvent API supports optional Datastream overrides. This allows you to adjust your datastreams without the need for new ones or modifications to existing settings. The process involves two steps:

1. Define your Datastream configuration overrides on the datastream configuration page.
2. Send these overrides to the Edge Network using the sendEvent API.

Note: You can find a tutorial for Datastream config overrides using rules here.

Syntax

sendEvent(experienceEvent: ExperienceEvent): Promise<Array<EdgeEventHandle>>

Example

const sampleXdmData  = {"eventType" : "SampleXDMEvent"};
const freeFormData  = {"free": "form", "data": "example"};
let experienceEvent = new ExperienceEvent({xdmData: sampleXdmData , data: freeFormData});

// send ExperienceEvent ignoring the promise
Edge.sendEvent(experienceEvent);

// send ExperienceEvent with promise
Edge.sendEvent(experienceEvent).then(eventHandles => console.log("Edge.sentEvent returned EdgeEventHandles = " + JSON.stringify(eventHandles)));

Example with Datastream ID override

const sampleXdmData  = {"eventType" : "SampleXDMEvent"};

let experienceEvent = new ExperienceEvent({xdmData: sampleXdmData, datastreamIdOverride: 'SampleDataStreamId'});

// send ExperienceEvent ignoring the promise
Edge.sendEvent(experienceEvent);

Example with Datastream config override

const sampleXdmData = { eventType: 'SampleXDMEvent' };
const configOverrides = {
    com_adobe_experience_platform: {
      datasets: {
        event: {
          datasetId: 'SampleEventDatasetIdOverride',
        },
      },
    },
    com_adobe_analytics: {
      reportSuites: ['sampleRSID'],
    }
   };

let experienceEvent = new ExperienceEvent({xdmData: sampleXdmData, datastreamConfigOverride: configOverrides});


// send ExperienceEvent ignoring the promise
Edge.sendEvent(experienceEvent);

Public classes

EdgeEventHandle

The EdgeEventHandle is a response fragment from Adobe Experience Platform Edge Network for a sent XDM Experience Event. One event can receive none, one or multiple EdgeEventHandle(s) as response.

class EdgeEventHandle {
  type?: string;
  payload?: Array<Record<string, any>>;

  constructor(type?: string, payload?: Array<Record<string, any>>) {
    this.type = type;
    this.payload = payload;
  }
}

export default EdgeEventHandle;

ExperienceEvent

Experience Event is the event to be sent to Adobe Experience Platform Edge Network. The XDM data is required for any Experience Event being sent using the Edge extension.

Usage

  //Experience Event setting with objects, recommended way to create experience event
  ExperienceEvent({xdmData: xdmData, data: data, datasetIdentifier: datasetIdentifier});
  ExperienceEvent({xdmData: xdmData, data: data, datastreamIdOverride: datastreamIdOverride});
  ExperienceEvent({xdmData: xdmData, data: data, datastreamConfigOverride: datastreamConfigOverride});

  //Experience Event setting with parameters, previously supported
  ExperienceEvent(xdmData, data, datasetIdentifier);

Example

//Example 1
// set free form data to the Experience event
const sampleXdmData  = {"eventType" : "SampleXDMEvent"};
const freeFormData  = {"free": "form", "data": "example"};

let experienceEvent = new ExperienceEvent({xdmData: sampleXdmData, data: freeFormData});

//Example 2
// Set free form data and datastream id override to the current Experience event:
const sampleXdmData = { eventType: 'SampleXDMEvent' };
const freeFormData  = {"free": "form", "data": "example"};

let experienceEvent = new ExperienceEvent({xdmData: sampleXdmData, data: freeFormData, datastreamIdOverride: 'SampleDataStreamId'});

//Example 3
// Set datastream config override to the current Experience event:
const sampleXdmData = { eventType: 'SampleXDMEvent' };
const configOverrides = {
    com_adobe_experience_platform: {
      datasets: {
        event: {
          datasetId: 'SampleEventDatasetIdOverride',
        },
      },
    },
    com_adobe_analytics: {
      reportSuites: ['sampleRSID'],
    }
   };

let experienceEvent = new ExperienceEvent({xdmData: sampleXdmData, datastreamConfigOverride: configOverrides});

Next steps - Schemas setup and validation with Assurance

For examples on XDM schemas and datasets setup and tips on validating with Assurance, refer to the Edge Network tutorial.