Introduction

PlatformX helps platform teams gather in-the-moment feedback from their users. PlatformX supports various types of projects including internal web apps, CLI tools, build scripts, and code libraries. PlatformX works by tracking events from your internal developer tools, then letting you send surveys that are triggered by specific events, chosen from the pool of events you are tracking.

Creating projects

Projects in PlatformX represent a single internal app, script, or library. Before creating a project, ensure that you have programmatic access to email addresses or GitHub usernames of users who interact with your app or tool.

To create a project, browse to the PlatformX tab in DX and click “Create project”. Then enter the name of your internal app, script, or library.

Tracking events

You can track events for apps, scripts, services, and CLIs using the PlatformX events API (see an example using GitHub Actions).

To track an event, make a POST request to the API method below with your API key passed as an HTTP Bearer token in your request header. You can find your API key in your project settings.

https://api.getdx.com/events.track

Arguments must be included in the POST body as either application/json or application/x-www-form-urlencoded, as shown in this example request:

curl https://api.getdx.com/events.track -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key here>" \
  -d '{"name": "your.event", "email": "[email protected]", "timestamp":"1680723287" }'

Required arguments

Property	Description
name	Name of the event. Example: `action-executed`
timestamp	A string containing the Unix timestamp for when the event occurred. Example: `"1680723287"`
email * required unless github_username or gitlab_username is provided	The email address of the user who initiated the event. Example: `[email protected]`
github_username * required unless email or gitlab_username is provided	The GitHub username of the user who initiated the event. Note: To attribute events by GitHub username, usernames must first be loaded into DX (instructions) Example: `jsmith`
gitlab_username * required unless email or github_username is provided	The GitLab username of the user who initiated the event. Note: To attribute events by GitLab username, usernames must first be loaded into DX (instructions) Example: `jsmith`

Optional arguments

Property	Description
metadata	Additional data about the event that you wish to capture. Example: `{"color": "blue"}`
test_data	Set this to true to create an event that will bypass the throttling logic and always send a survey, even before it is published. This event and the related response will appear in the app but not in reports or charts. Example: `true`

Example request

curl https://api.getdx.com/events.track -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key here>" \
  -d '{"name": "your.event", "email": "[email protected]", "timestamp":"1680723287", "metadata": { "color": "blue" }, "test_data": true }'

Evaluating responses

Responses from the API are in JSON format. Successful requests return an ok: true status, while errors provide ok: false with an error code and message.

HTTP Status Codes

200 - Request succeeded.
422 - There was an error with your request.
429 - Rate limit exceeded

Success Response Body

The response will always contain an ok property which is true when it is successful:

{ "ok": true }

Error Response Body

When there is an error, the ok property will be false and details about the error will be included.

{
  "ok": false,
  "error": "invalid_arguments"
}

Error Codes

Error Code	Description
`invalid_arguments`	This error occurs if we are unable to parse the parameters. Check that you are sending the timestamp in the expected format and all required parameters are included.
`invalid_form_data`	Make sure all required parameters are included.
`rate_limit_exceeded`	You attempted to send more than 15,000 events in a 24h period.

Example for HTML / Javascript Tracking

The following is an example of sending an event when a user visits a page. You can also trigger events based on specific interactions, but the specifics will depend on your implementation.

<script> 
  window.addEventListener('load', function() { 
    const url = 'https://api.getdx.com/events.track';
    const apiKey = '<api key>';
    const data = { 
      name: "page.visit", // customize your event names
      email: "<email>", // replace this with dynamic data 
      timestamp: Math.floor(Date.now() / 1000).toString(),
      metadata: { 
        page: window.location.href, // Optionally track the page URL 
        referrer: document.referrer // Optionally track referrer
      }
    }; 

    fetch(url, { 
      method: 'POST', 
      headers: { 
        'Content-Type': 'application/json', 
        'Authorization': `Bearer ${apiKey}`
      }, 
      body: JSON.stringify(data) 
    }); 
  }); 
</script>

Code libraries

You can track utilization and feedback of code libraries through PlatformX by implementing usage detection within your CI platform (e.g., GitHub Actions). To set up PlatformX with code libraries, create a CI workflow that scans pull request diffs and uses regular expressions to detect when your code library has been added or used. Then, conditionally fire events to PlatformX to capture this data, where it can then be used for analytics purposes and survey triggers.