Acoustic Exchange is an integration framework that allows different offerings to exchange data seamlessly so that businesses can understand their customer's behaviors across multiple applications and channels.
Exchange works on a publish and subscribe model. Publishers register and send event data to Exchange, and the destination endpoints (known as subscribers) register and receive the event data and present it in their own format. Each product that is registered in Exchange has their own presentation layer.
With Exchange, you can share customer event data between Exchange-enabled products, including Acoustic Tealeaf for a broader and deeper understanding of your customer's experiences and behaviors.
Presently, Tealeaf acts only as publisher of event data. For example, as a publisher in the Exchange ecosystem, Tealeaf might capture data from a cart abandonment event and then publish that data. A subscriber application in the Exchange ecosystem (Acoustic Campaign for example) captures and presents data from the cart abandonment event in their own model and framework.
Responsibility by user role for publishing event data to Exchange
Integrating Tealeaf with Acoustic Exchange spans multiple user roles as described here.
Administrator role
Responsibility: Registers the endpoint for Tealeaf in Acoustic Exchange.
The endpoint registration sets the deployment details (such as which Tealeaf data center to connect to) and generates an Acoustic Exchange authentication key.
The authentication key serves as the security token, which allows Tealeaf to publish event data to Exchange.
The authentication key is added to the Exchange auth key field on the Company Settings page automatically, or manually, depending on options selected in Exchange.
The direct connect option generates, activates, and adds the authentication key to the Exchange auth key parameter on the Tealeaf Company Settings page.
The instructions only option generates the authentication key in a "pending" state.
You can copy and paste the key into the auth key parameter on the Tealeaf Company Settings page.
For information about registering endpoints in Exchange, see the Acoustic Exchange help center.
User or any role with access to the Event manager
Responsibility: Create Exchange events with the Event manager.
There are two ways to create Exchange events that publish event data from Tealeaf to Acoustic Exchange:
- Configure ready-to-use Exchange events to publish event data
- Send data to Exchange with your own Exchange events
Regardless of which method you use, the events that you publish from Tealeaf to Exchange must adhere to the taxonomy in Exchange.
Configure ready-to-use Exchange events to publish event data
If your organization is planning on publishing event data from ready-to-use Exchange events, make sure your administrator has registered Tealeaf as an endpoint in Exchange, and that the Exchange integration settings for your organization are set on the Company Settings page.
When you create your events from the Event manager, you can configure the event to be an Exchange event.
Tealeaf comes with 23 ready-to-use Exchange events that you can configure to publish event data to Acoustic Exchange.
If you want to send event data from Tealeaf to Exchange, you need to:
- Specify identifiers for your Exchange event
- Configure the event to be an "Exchange event"
Specify identifiers for your Exchange events
Set up your Exchange event to capture identifiers
Tealeaf works on a "session level". So, to capture the information that identifies the customer, you create session attributes.
- Phone
- Login
- Device ID
Configure your Exchange event
To configure an event to be an Exchange event, set the category and event options from the Exchange event section of the Event manager.
The categories, events, and associated prerequisite attributes in the Exchange event section of the Event manager, map to the event taxonomy used by Exchange.
The Exchange-supported categories and events listed in the Exchange event section of the Event manager can also be found in Acoustic Exchange, in the Exchange Dynamic Event Library. The library is an interactive guide of the event types that are recognized by Acoustic Exchange, and the publishers and subscribers that support the Events.
Having access to the Exchange Dynamic Event Library can help you understand how to set the attributes and conditions for the Exchange event.
For information about Acoustic Exchange events and the Dynamic Event Library, see the Acoustic Exchange help center.
- Tealeaf publishes data from the event to Exchange.
- Acoustic Exchange processes the data that is generated from the Exchange event configuration only, and ignores everything else from the event definition.
- Tealeaf processes the Event normally based on the conditions and parameters outside of the Acoustic Exchange parameters.
Subscribers to the Tealeaf application in Exchange, capture the event data and display it in their application, by using their own framework.
Whenever you create a new Exchange event from the Event manager, the Administrator can go to the endpoint in Acoustic Exchange and subscribe to the newly created Event.
For an end-to-end scenario on how to implement ready-to-use Exchange events,see Create a campaign that targets cart abandonment causes.
Send data to Exchange with your own Exchange events
If you are planning on publishing event data from your own Exchange events, make sure your administrator has registered Tealeaf as an endpoint in Exchange, and that the Exchange integration settings for your organization are set on the Company Settings page.
If none of the 23 ready-to-use Exchange events address your business needs, you can use your own Exchange events that send event data to Exchange.
To send your own event that publishes event data to Exchange, you must add JavaScript API code to the Advanced mode window in the Event manager.
The JavaScript variables expose two new API calls:
$S.addExchangeIdentity$F.sendExchangeEvent
With the JavaScript code that you add to the Advanced mode window, you can send your own identities and events to Exchange, as long as the data being sent adheres to the Exchange taxonomy.
Note: Publishing events to Exchange using the Advanced mode is very unrestricted and requires an understanding of how to code advanced events, as well as an understanding of how Exchange processes event data. If you are defining your own Exchange events, we recommended you work with Acoustic services implement them in a solution.
As long as the identity and event data being published adheres to the Exchange taxonomy, the way you capture and publish data from your own Exchange event does not matter. For example, if you send an Exchange event via the Advanced mode, you are not obligated to send the Exchange identity in the same manner. You can still use the Exchange identity feature in the Event manager to send identity data for the Exchange events sent via the Advanced mode. You can also use of the Exchange identity feature of Event manager together with Advanced mode to send multiple identities to Exchange.
About $S.addExchangeIdentity
The $S.addExchangeIdentity includes a set of name / value pairs that are sent into the Exchange ecosystem.
Acoustic Exchange can join different identifier attributes across different endpoints to develop a rich view of specific customer behavior over time and in different situations. For this reason, its imperative that the name / value pairs that you specify for $S.addExchangeIdentity be as unique as possible.
Sample code for $S.addExchangeIdentity
In the Advanced mode window, add the identifier information. Use the following usage pattern as template for sending the Exchange identity.
// NOTE: Do not change event name
function E_EXCHANGE_SEARCHEDSITE_1594319517384()
{
if ($S.Duration >= 0)
{
// $S.addExchangeIdentity("recipient", "test001@test.com");
$F.setFacts("E_EXCHANGE_SEARCHEDSITE_1594319517384");
var attrs = [];
var searchTerm = $S.PLATFORM_OS;
}
}
//
About $F.sendExchangeEvent
The $F.sendExchangeEvent method accepts 4 inputs as follows:
| Method | Inputs | Required? | Guidance |
| $F.sendExchangeEvent | eventCode | Yes | The value must conform to the Event type code added to the Tealeaf application in Acoustic Exchange. |
| eventName | No | Pass null if no value. | |
| channel | No | Pass null if no value. The system derives this value from the "Platform" session attribute. | |
| Attributes | No |
Pass empty array or null. Be sure to adhere to the taxonomy guidelines for the specific event code. Code the addExchangeIdentity function |
Events defined in the Exchange taxonomy must be also be added to the "Acoustic Experience Analytics on Cloud" application in Exchange.
For general information about using the Advanced mode to create events, see .
Sample code for $F.sendExchangeEvent
In the Advanced mode window, add the event information and the event attributes. The attributes must adhere to the Acoustic Exchange taxonomy requirements. Use the following usage pattern as template for sending the Exchange event.
// NOTE: Do not change event name
function E_EXCHANGE_SEARCHEDSITE_1594319517384()
{
$F.sendExchangeEvent("acousticearchedSite", null, "custom channel", attrs);
}
}
//
- Tealeaf publishes data from the event to Exchange.
- Acoustic Exchange processes the data that is generated from the Exchange event configuration only, and ignores everything else from the event definition.
- Tealeaf processes the Event normally based on the conditions and parameters outside of the Acoustic Exchange parameters.
Exchange code sample
In the Advanced mode window, add the identifier information for the event and the event attributes. The attributes must adhere to the Acoustic Exchange taxonomy requirements. Use the following usage pattern as template for building the Exchange event.
// NOTE: Do not change event name
function E_EXCHANGE_SEARCHEDSITE_1594319517384()
{
if ($S.Duration >= 0)
{
$S.addExchangeIdentity("recipient", "test001@test.com");
$F.setFacts("E_EXCHANGE_SEARCHEDSITE_1594319517384");
var attrs = [];
var searchTerm = $S.PLATFORM_OS;
attrs.push({"name":"searchResultCount", "value": 123, "type":"NUMBER"});
attrs.push({"name":"searchTerms", "value": searchTerm, "type":"STRING"});
attrs.push({"name":"searchType", "value": "landing page search", "type":"STRING"});
$F.sendExchangeEvent("ibmsearchedSite", null, "custom channel", attrs);
}
}