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": "your.email@example.com", "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: `jsmith@getdx.com`
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": "your.email@example.com", "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.

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"
}

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.