Protocols API

Protocols customers receive early access to Segment’s Platform API, which enables programmatic creation, configuration, and fetching of core Segment platform resources such as Sources, Destinations, and now Tracking Plans. The Platform API represents Segment’s commitment to developers, enabling customers to extend their workflows around customer data collection and activation. The Platform API will be generally available to customers in coming months and will be evolving with more functionality throughout next year.

Supported Operations

• List Tracking Plans
• Get Tracking Plan
• Create Tracking Plan
• Update Tracking Plan
• Delete Tracking Plan

Comprehensive documentation with Guides, Tutorials, and References for the Platform API is available to Protocols customers in our Developer Portal, which is currently private. For access, just

Debug Endpoint

This endpoint enables customers to send sample .track(), .identify(), .group(), .page() and .screen() requests to a debug endpoint that will return an error response if that payload is invalid. The event payload will not be delivered to the Segment Source or any active Destinations. Customers can use this endpoint in testing suites or to test payloads against current Schema filters or a Tracking Plan spec. Follow the instructions below to test sample payloads without delivering the event to Segment or downstream Destinations.

Authentication: This endpoint uses the same Authentication protocol outlined in our HTTP docs.

Enable debug mode with Analytics.js

The following snippet can be added to your dev environment or executed in a web console to use the debug endpoint. When enabled, all outbound Segment events will hit the debug endpoint. Events will not be delivered to Segment Destinations, so make sure to disable this when deploying your code to production.

analytics.Integrations["Segment.io"].prototype._enqueue = analytics.Integrations["Segment.io"].prototype.enqueue;
analytics.Integrations["Segment.io"].prototype.enqueue = function(path, msg, fn) {
  this.options.apiHost = 'debug-api.segment.com/v1'
  return this._enqueue(path, msg, fn)
};

Enable debug mode with querystring flag

Analytics.js does not have a built-in ‘debug mode’ flag yet. You can add a querystring flag to your Segment instrumentation with the following snippet:

// Point to the debug-api when the URL contains the query param "?segment_debug=true"

var apiHost;
if (window.location.href.indexOf('segment_debug=true') !== -1) {
  apiHost = 'debug-api.segment.com/v1';
} else {
  apiHost = 'api.segment.io/v1';
}

analytics.load("YOUR_WRITE_KEY", {
  integrations: {'Segment.io': { apiHost: apiHost } }
});

NOTE: Make sure this is only used in development environments since the debug-api does not send data downstream!

Error responses

The debug endpoint API will return detailed errors depending on the violation generated.

End to End API Example

NOTE: These APIs are beta, which means that their names and functionality might change. If you find any bugs or have any feedback, please contact us.

Create a Personal Access Token

Programmatic access to the Segment Platform API for resources that you own happens through personal access tokens. Personal access tokens belong to Segment users, and can be used to access resources owned by the user who created them.

To set up Segment Protocols through the API you first need to create a personal access token with full access to your workspace through the workspace scope. Use your Segment account email and password:

$ [email protected]
$ PASS=<redacted>

$ curl \
  -d '{"access_token": {"description": "my access token", "scopes": "workspace", "workspace_names": ["workspaces/example"]}}' \
  -u "$USER:$PASS" \
  https://platform.segmentapis.com/v1alpha/access-tokens

Example response:

{
  "name": "access-tokens/5",
  "description": "my access token",
  "scopes": "workspace",
  "workspace_names": ["workspaces/example"],
  "create_time": "2018-10-12T22:36:39Z",
  "token": "qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g"
}

NOTE: You can not retrive the plain-text token after this so write it down or store it programmatically.

Create a Source

The Platform API enables you to create event sources, each of which has a corresponding unique “write key” that you configure the Segment SDK with.

Let’s create an event source to see how the Tracking Plan works on data we send to it:

$ ACCESS_TOKEN=<ACCESS-TOKEN-VALUE>

$ curl \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"source": {"name": "workspaces/example/sources/js", "catalog_name": "catalog/sources/javascript"}}' \
  https://platform.segmentapis.com/v1alpha/workspaces/example/sources

Example response:

{
 "name": "workspaces/example/sources/js",
 "parent": "workspaces/example",
 "catalog_name": "catalog/sources/javascript",
 "write_keys": [
  "LxKXARX9IuqR9v0gn7y2Fw1iHi0ephbF"
 ],
 "create_time": "2018-09-12T21:15:54.169Z",
 "library_source_config": {}
}

For good measure, let’s send a couple of events to our new Source. Note that event and userID are required. See the Tracking API spec for more details.

$ WRITE_KEY=LxKXARX9IuqR9v0gn7y2Fw1iHi0ephbF

$ curl https://api.segment.io/v1/track \
  -u $WRITE_KEY: \
  -H 'Content-type: application/json' \
  -d '{
    "event": "User Logged In",
    "userId": "78e56a08-ad10-42b1-88d2-b823623ac875",
    "properties": {
      "username": "user1"
    }
  }'

$ curl https://api.segment.io/v1/track \
  -u $WRITE_KEY: \
  -H 'Content-type: application/json' \
  -d '{
    "event": "User Login",
    "userId": "45677435-e419-475D-a884-c0a01bd36619",
    "properties": {
      "userName": "user2"
    }
  }'

To verify your events were sent to the Source, open the event debugger in your browser, e.g. https://app.segment.com/example/sources/js/debugger.

Create a Tracking Plan

Now we can configure a Tracking Plan on the workspace. Here we define that we only expect a single event User Logged In with a required username property. This will help us find and eliminate events with subtle differences like the name User Login or properties like userName, resulting in pristine data in Segment and all Destinations.

$ curl \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{
      "tracking_plan": {
        "display_name": "My Tracking Plan",
        "rules": {
          "events": [
            {
              "rules": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "properties": {
                  "type": "object",
                  "properties": {
                    "username": {
                    "description": "",
                    "id": "/properties/properties/properties/username",
                    "type": "string"
                    }
                  },
                  "required": [
                    "username"
                  ]
                }
              },
              "required": [
                "properties"
              ]
              },
              "name": "User Logged In",
              "description": "Sent when a user logs into the web app"
            }
          ]
        }
      }
    }' \
    https://platform.segmentapis.com/v1beta/workspaces/example/tracking-plans

Example response:

{
 "name": "workspaces/example/tracking-plans/rs_1AAPTLy8ffAAQth0PvL8rOvU6PJ",
 "display_name": "My Tracking Plan",
 "rules": {
  "events": [
   {
    "name": "User Logged In",
    "description": "Sent when a user logs into the web app",
    "rules": {
     "properties": {
      "properties": {
       "properties": {
        "username": {
         "type": "string",
         "description": "",
         "id": "/properties/properties/properties/username"
        }
       },
       "required": [
        "username"
       ],
       "type": "object"
      }
     },
     "required": [
      "properties"
     ],
     "$schema": "http://json-schema.org/draft-04/schema#",
     "type": "object"
    }
   }
  ]
 },
 "create_time": "2018-09-13T19:20:37Z",
 "update_time": "2018-09-13T19:20:37Z"
}

Update a Tracking Plan

Over time the Tracking Plan will evolve and include more events. We can update the plan to include another event User Created with a required username property:

$ curl \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -X PUT \
  -d '{
    "update_mask": {
      "paths": [
        "tracking_plan.display_name",
        "tracking_plan.rules"
      ]
    },
    "tracking_plan": {
      "display_name": "My Updated Tracking Plan",
      "rules": {
        "events": [
          {
            "rules": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "properties": {
                  "type": "object",
                  "properties": {
                    "username": {
                      "description": "",
                      "id": "/properties/properties/properties/username",
                      "type": "string"
                    }
                  },
                  "required": [
                    "username"
                  ]
                }
              },
              "required": [
                "properties"
              ]
            },
            "name": "User Logged In",
            "description": "Sent when a user logs into the web app"
          },
          {
            "rules": {
              "$schema": "http://json-schema.org/draft-04/schema#",
              "type": "object",
              "properties": {
                "properties": {
                  "type": "object",
                  "properties": {
                    "username": {
                      "description": "",
                      "id": "/properties/properties/properties/username",
                      "type": "string"
                    }
                  },
                  "required": [
                    "username"
                  ]
                }
              },
              "required": [
                "properties"
              ]
            },
            "name": "User Created",
            "description": "Sent when a user is created in the web app"
          }
        ]
      }
    }
  }' \
  https://platform.segmentapis.com/v1beta/workspaces/example/tracking-plans/rs_1AAPTLy8ffAAQth0PvL8rOvU6PJ

{
  "name": "workspaces/example/tracking-plans/rs_1AqjFLhQGTrpI7k3cipnSVF71n2",
  "display_name": "My Updated Tracking Plan",
  "rules": {
    "events": [
      {
        "name": "User Logged In",
        "description": "Sent when a user logs into the web app",
        "rules": {
          "required": [
            "properties"
          ],
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "properties": {
              "type": "object",
              "properties": {
                "username": {
                  "description": "",
                  "id": "/properties/properties/properties/username",
                  "type": "string"
                }
              },
              "required": [
                "username"
              ]
            }
          }
        }
      },
      {
        "name": "User Signed Up",
        "description": "Sent when a user signs up for the web app",
        "rules": {
          "$schema": "http://json-schema.org/draft-04/schema#",
          "type": "object",
          "properties": {
            "properties": {
              "required": [
                "username"
              ],
              "type": "object",
              "properties": {
                "username": {
                  "type": "string",
                  "description": "",
                  "id": "/properties/properties/properties/username"
                }
              }
            }
          },
          "required": [
            "properties"
          ]
        }
      }
    ]
  },
  "create_time": "2018-09-28T18:55:19Z",
  "update_time": "2018-09-28T18:58:03Z"
}

Connect Tracking Plan to Source and Start Blocking Non-Conforming Data

Now we can review the Tracking Plan and connect it to a Source.

Click on “My Tracking Plan” to open the editor and review the events.

Click on “…” to connect the Tracking Plan to the js source.

Now open the Source Schema in your browser, e.g. https://app.segment.com/example/sources/js/schema2/events. We can see the that one event we sent conforms to the plan, and the other does not.

Now we can go all-in on the Tracking Plan, and block events that don’t conform from being sent to Destinations. Click “Edit” next to “Unplanned Data”, and select “Block” for unplanned track calls.

From here, we can also configure a Source to receive violation notifications

You can verify how the Tracking Plan works by sending events to the debug-api.segment.com endpoint.

We’ll use the write keys returned from the creation operation against the Sources API as the password to the debug tracking API.

Example command:

$ curl https://debug-api.segment.com/v1/track \
  -u $WRITE_KEY: \
  -H 'Content-type: application/json' \
  -d '{
    "event": "User Logged In",
    "userId": "78e56a08-ad10-42b1-88d2-b823623ac875",
    "properties": {
      "username": "user1"
    }
  }'

Example response:

{
  "success": true
}

Example command:

$ curl https://debug-api.segment.com/v1/track \
  -u $WRITE_KEY: \
  -H 'Content-type: application/json' \
  -d '{
    "event": "User Logged In",
    "userId": "78e56a08-ad10-42b1-88d2-b823623ac875",
    "properties": {
      "userName": "user1"
    }
  }'

Example response:

{
  "success": false,
  "message": "properties.username: properties.username is required"
}

Example command:

$ curl https://debug-api.segment.com/v1/track \
  -u $WRITE_KEY: \
  -H 'Content-type: application/json' \
  -d '{
    "event": "User Login",
    "userId": "45677435-e419-475D-a884-c0a01bd36619",
    "properties": {
      "userName": "user2"
    }
  }'

Example response:

{
  "success": false,
  "message": "Disabled event"
}

Google Sheets Tracking Plan Uploader

Thousands of Segment customers have used Google Sheets to build Tracking Plans. We created the following template to help you draft a Tracking Plan and easily upload that Tracking Plan to Segment. Keep in mind that uploading changes from Google Sheets will overwrite any changes made within the Segment UI.

To upload your Tracking Plan directly from Google Sheets, follow these steps:

1. Generate an App following the steps here
2. Copy your App Client ID and Secret and your tracking plan’s rs_ id (found in the URL path of your Tracking Plan) to the Importer Settings worksheet. Then click on the Segment > Send to Segment menu item to upload your Tracking Plan to Segment.

If you have any questions, or see anywhere we can improve our documentation, please let us know!