This document contains the following sections:

• Outcomes and Audience
• Data in MetaCX
• Creating a Connection to your App
• Sending Events to MetaCX
  
  • Posting Events via the Event Handler Connection
  • Installing the Tracking Script in Your App

Outcomes and Audience

After using this guide, you will understand:

	The core concepts of MetaCX
	How to create a Connection
	How to send events to your Connection
	How to install the MetaCX tracking script in your application

This document is most useful for software engineers who:

• Author the scripts that send events to MetaCX.
• Install the MetaCX tracking script into your app.

Data in MetaCX

Your business has a variety of business systems, or event sources, that track events related to your customers’ success. Your team wants to aggregate these events in MetaCX, parse them according to criteria, and use that knowledge to make customers more successful. 

The events your team wants to track are, of course, specific to your team. They depend on what event sources you have, what Metrics you collect, and what Outcomes you care about. 

The part of MetaCX that processes your events is the CXReactor. You can create a Connection through the UI or API. A Company represents each of your clients in MetaCX. MetaCX aggregates data from various systems together under the Company.

Once you have events flowing in, you or someone else on your team applies criteria to the events to emit Signals. The process of configuring the Signal includes a step to map a MetaKey, which identifies the Company in MetaCX, to the company identifier you use in your system. It can also include a step to output a Data Feed. 

Once you’ve set up your Signals, your team will have the raw materials to create Metrics, which contribute to Success Milestones, which determine Outcomes and ultimately reflect the success of your clients.

MetaCX Platform Visualization

Creating a Connection to your App

You define a Connection so MetaCX can generate the information you need to send events. You can send events via an event handler using the API or by installing a tracking script in your app. Procedures for both approaches following this procedure. For this procedure, you just need to configure the Connection to expect the method you intend to use to send the events.

Use these steps to connect your app to MetaCX so that you can send events to the Connection.

1. Go to the CXReactor.
2. Click the Connections icon in the upper right-hand corner. The Connections view appears.
3. Click the Manage Connections button and then click the Add Connection option from the menu that appears. A new Connection appears for you to configure.
   Tip: The Manage Connections button appears in the lower right-hand corner of the screen.
4. Give the Connection a name.
   Tip: For easy maintenance in the future, name the Connection after the event source. For example, "HubSpot" or "Salesforce" can be good Connection names. In this case, the name of your app is probably best.
5. Select one of the following Connection types:

• Generate Event Handler on Save: Choose this if you are creating a Connection that posts events via the API. After you click Save, a Show Keys link appears. Click the link to see the Client ID and Client Secret you need to make your Connection.
  
• Generate Tracking Script on Save: Choose this if you are creating a Connection that will use a tracking script. After you click Save, a Show Tracking Script link appears that you can click to see the Analytics Key and Tracking Script you’ll use in your app.
  
  Note: A third option, Generate Machine to Machine Connection on Save, also appears here, but it is not suitable for this procedure.

Tip: You can set up a Connection to your test environment before you deploy the changes to your production app. Follow the same steps to create a special test Connection to your app's test environment. When you have the code working in your test environment, you can copy it to production and just swap out the test Client ID/Client Secret or Analytics Key/Tracking Script with the values from the Connection you set up for production. Please remember to name your Connections accordingly, for example including "Test Env” in the name of the test Connection.

Sending Events to MetaCX

You can send events to MetaCX by posting them or by setting up a tracking script. This section discusses both approaches, but you use only one approach per Connection you set up in MetaCX.

Posting Events via the Event Handler Connection

Important Prerequisite:

For all events being sent to a MetaCX connection (or using the API) you must ensure that you are using TLS (Transport Layer Security) 1.2 or later. As of August 15th, 2020 MetaCX will not accept any connections that use TLS 1.0 or TLS 1.1.

The endpoints in question are:

https://api.metacx.com/

and

https://app.metacx.com/

For more information on TLS please navigate to its most updated Wikipedia page: https://en.wikipedia.org/wiki/Transport_Layer_Security

To post events to the events API, you need to acquire an access token. In order to get an access token, you need to provide your Client ID and Client Secret and POST the following HTTP request to MetaCX. 

Tip: You can find the Client ID and Client Secret in the Connection you created in the previous section of this document.

POST /getToken HTTP/1.1
Host: api.metacx.com
Content-Type: application/json

{
        "clientId": "<your client id>",
        "clientSecret": "<your client secret>"
}

HTTP/1.1 200 OK

{
    "accessToken": "<your access token>",
    "scope": "read:api user_profile",
    "expiresIn": 86400,
    "tokenType": "Bearer"
}

Use the returned access token to post events using the HTTP request below. The API immediately queues the event for processing and return a 202 Accepted response. 

The example below posts an event when a user logs in to your product.

POST /events HTTP/1.1
Host: api.metacx.comContent-Type: application/json
Authorization: Bearer <access token here>

{
     "eventKey": “logins”,
     "data": [{
          "eventDate”: <event date here>,
          "name": “<account name here>“,
          "accountId": “<account id here>“,
          “userId”: “<user id here>
     }]
}

HTTP/1.1 202 Accepted

{
  "requestId": "<id for this request>"
}

Field Descriptions

Important: If you do not specify an event date, the MetaCX platform aggregates the event data by the date/time when it processed the event. In most cases, people using MetaCX need the data to reflect the time the event actually happened. That’s why it is important to set the event date, especially if you post events in batches. You can set the eventDate on every event in the data array. The format should be a Unix timestamp in milliseconds. In JavaScript, this is equivalent to Date.now();  

Idempotency Notes:

Uniqueness - This value should be unique for the event. While an incrementing integer (as a string) will work, it is recommended to use a string with at least 16 bytes of randomization, such as a UUID or GUID.

Single processing guarantee - In case you send us an event with the same key more than once, the new event will not be processed. It will show in the event log as received, but no further processing will occur.

SHA512 - Our system will SHA512 this idempotencyKey along with the connectionId and eventKey. While statistically this is not an issue, there is an extremely small chance of a collision.

Retry failed requests to resolve server errors: 

You can periodically retry failed requests that result in responses with HTTP status code 500-599 over an increasing amount of time to handle errors related to rate limits, network volume, or response time. For example, you might retry a failed request after one second, then after two seconds, and then after four seconds. This method is called exponential backoff and it is used to improve bandwidth usage and maximize throughput of requests in concurrent environments.

Installing the Tracking Script in Your App

You can use the MetaCX tracking script to stream analytic events to MetaCX from within your application. The script wraps all of the functionality required to capture the event (like button clicks) and all of the data associated with the event. 

Note: All MetaCX API requests must use TLS/SSL. All other requests will be refused.

Use the following steps to install the tracking script. These steps pick up from where you created a Tracking Script Connection in the procedure earlier in this document:

1. Access the tracking script by clicking the Show Tracking Script link on the Connection you created.
2. Copy the text in the Tracking Script field and paste it into your index.js or web page.
3. Set the fields to establish the context of your logged in user. See the Field Descriptions table below.
4. Call window.mcxTrack('eventKey', payload) to send your data to MetaCX.
   • You should replace eventKey with the string you use to identify and track your event. The eventKey string must not begin with a dollar sign character ($) and must not include the colon character (:) or the period character (.).
   • payload is any JSON object containing event details you want to appear in MetaCX. Currently MetaCX consumes only root-level key/values; it does not traverse nested objects. However, nested objects may be sent.

Field Descriptions

What’s Next?

Now that you’ve created your first Connection and have successfully sent Events you can start branching out. Over time, you’ll want to send a variety of events from a number of event sources to MetaCX so that you can keep tabs on how customers are performing. 

Beyond your own app, Salesforce can be an excellent source of events. You can send events to the MetaCX platform using APEX triggers. The code samples in the linked project will send Account record insert and update events to a MetaCX Connection. The instructions are included in the Readme in the repository:

https://github.com/metacxdev/com.metacx.apex

When you have data flowing in, you want to configure MetaCX to process it. See Creating Signals and Data Feeds for next steps.