ActivEngage SDK Documentation

Digital Retailing Guide

General Considerations

There are are a couple of primary goals we wish to accomplish here.

  1. Allow the operator to have a proper context for which the conversation is taking place. With that context their ability to help the consumer as they navigate the DR tool will be greatly enhanced.
  2. Help the dealer complete more deals with their respective DR tool.

For DR tools that utilize iFrames see the iFrame Section of this document for tools that will specifically support that use case.

Deal Info

In order to provide context to the operator we provide methods to pass data into the chat.

setDealInfo

This method passes the basic data that will be included when the chat is answered or be appended to the chat when called.

Param: JSON Object

  • dealId - A unique ID we can pass a long for reporting purposes.
  • dealUrl - A URL that the operator can click to see details about the current deal.
  • dealName - A friendly name to display to the operator.

setDealSections

This method passes the sections available to consumer to complete the deal. You can call pushSectionProgress to let the operator as the consumer moves through these sections. Ideally the number of sections here would be 4 - 6. Any more and it can be difficult for the agent to easily follow.

Param: JSON Object

  • sections - An array of available sections the consumer needs to complete.

Example

<script>
var onReady = function() {
  /* Setting this immediately allows us to capture the data for new 
     conversations and to append for existing ones. */
  ActivEngage.retailing.setDealInfo(
    {
      'dealId': '[[dealId]]', 
      'dealUrl': '[[dealUrl]]', 
      'dealName': '[[dealName]]'
    }
  );

  // this allows the chat agent to monitor progression through the deal
  ActivEngage.retailing.setDealSections({
    sections: ["General", "Credit", "Trade", "Options", "Final"]
  });

  document.body.setAttribute('chat-ready', 'onReady()');
</script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

pushSectionProgress

As the consumer progresses through the deal you can call this method to update the operator on their progress.

Param: JSON Object

  • sectionName - Name of the section to update. Should match a section provided in setDealSections.
  • sectionStatus - The status of the section being updated. (Enum options are in ActivEngage.retailing.constants.progress)
  • sectionData - Array of JSON Objects [{fieldName: "", fieldValue: ""}, ...]

Example


// Example setting status to InProgress
ActivEngage.retailing.pushSectionProgress({
  sectionName: "General", 
  sectionStatus: ActivEngage.retailing.constants.progress.inProgress, //options are none, inProgress, incomplete, completed
  sectionData: [{fieldName: "First Name", fieldValue: "Andrew"}, {fieldName: "Last Name", fieldValue: "Shansky"}]
});

// Example setting status to Completed
ActivEngage.retailing.pushSectionProgress({
  sectionName: "General", 
  sectionStatus: ActivEngage.retailing.constants.progress.completed,
  sectionData: [{fieldName: "First Name", fieldValue: "Andrew"}, {fieldName: "Last Name", fieldValue: "Shansky"}]
});

// Example setting fieldValue for sensitive fields
// - to avoid sending sensitive fields place the string "COMPLETED" in the fieldValue 
ActivEngage.retailing.pushSectionProgress({
  sectionName: "Credit", 
  sectionStatus: ActivEngage.retailing.constants.progress.completed,
  sectionData: [{fieldName: "SSN", fieldValue: "COMPLETED"}]
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

iFrame Use Case

DR tools that utilize iFrames have special cases that need to be managed.

  • Maintaing chat and visitor data when crossing domain boundaries.
  • Preventing chat CTAs from being display twice.

Generate session identifier

To carry data over between the dealer's site and the DR iFrame you can call createSessionToken to generate an AE session token. This method returns a promise that supports done and fail methods.

  ActivEngage.tracking.createSessionToken()
    .done(function(token) {
      let sessionToken = token;
    })
    .fail(function(){
      console.log("Unable to create a session token");
    });
  // token must be passed to the pageview script load inside your iframe
1
2
3
4
5
6
7
8

Hide AE CTAs

In order to prevent duplicate chat CTAs from appearing first hide the AE widgets on the dealer outer frame by calling ActivEngage.widgets.hide();

if (ActivEngage) {
  ActivEngage.widgets.hide();
}
1
2
3

Load ActivEngage in iFrame

ActivEngage's pageview script is loaded with a single script reference. Two query string params are added so that the correct account and visitor data is loaded.

Params

  • chat-account - The dealer ID and should be provided by ActivEngage.
  • session-token - The token created in the createSessionToken method.

Examples

// prod
<script async defer 
  src="https://pageview.activengage.com/js/pageview.min.js?chat-account=[dealer-domain]&session-token=[session-token]"></script>

//qa
<script async defer 
  src="https://pageview-qa.activengage.com/js/pageview.min.js?chat-account=[dealer-domain]&session-token=[session-token]"></script>

//dev
<script async defer 
  src="https://pageview-dev.activengage.com/js/pageview.min.js?chat-account=[dealer-domain]&session-token=[session-token]"></script>
1
2
3
4
5
6
7
8
9
10
11
12

Show AE CTAs

Upon completion of the deal or if the consumer closes the deal frame, please re-show the ActivEnage CTAs.

if (ActivEngage) {
  ActivEngage.widgets.show();
}
1
2
3

Demo

iFrameopen in new window

Last Updated: 10/14/2025, 2:20:10 PM