Stories Destination


Stories gathers all the user events that matter on a timeline, so your teams can understand what is going on and take action in the right direction.

This destination is maintained by Stories. For any issues with the destination, please reach out to their team.

NOTE: The Stories Destination is currently in beta, which means that they are still actively developing the destination. This doc was last updated on February 7, 2020. If you are interested in joining their beta program or have any feedback to help improve the Stories Destination and its documentation, please let their team know!

Getting Started

  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “Stories” within the Destinations Catalog and confirm the Source you’d like to connect to.
  3. Drop in the “API Key” into your Settings UI which you can retrieve from your Stories Account.
  4. You can choose whether to Sync Users or not with Stories. If you enable this setting, identified users will be automatically added and/or merged with your Stories users. Read more about Merging Users below.

Identify

An identify call is sent to Stories as a new event on a user’s timeline. This call is mainly used to keep track of changes to users’ profile and maintain user properties called traits in Segment. If you want to track specific user actions we recommend using the track call.

Only identify calls update the Profile traits and Attributes on the left-hand side of user profiles. track, page, and screen calls create users but don’t populate user Attributes.

userId is a required property to assign the call to a specific user. Stories does not support anonymous user tracking. An example call would look like with a server-side call:

POST api.getstories.io/v1/events/
Params: {
  user_id: "some_user_id", //Segment’s userId
  name: "Identify", //Segment’s call type
  data: {
      traits: { //Segment’s traits for the user
          first_name: "Jacob"
      }
  }
}

Page & Screen

A page and/or a screen call will be sent to Stories as a new event on a user’s timeline as a visited Page or opened Screen. userId is a required property to assign the call to a specific user. name is a recommended field that helps identify the event characteristics but not required. An example server-side call:

POST api.getstories.io/v1/events/
Params: {
  user_id: "some_user_id", //Segment’s userId
  name: "Page", //Segment’s call type
  data: {
      content: "FAQ - Help" //Segment’s name
  }
}

POST api.getstories.io/v1/events/
Params: {
  user_id: "some_user_id", //Segment’s userId
  name: "Screen", //Segment’s call type
  data: {
      content: "App went Foreground" //Segment’s name
  }
}

Track

A track call will be sent to Stories as a new event on a user’s timeline to keep a track of user actions. userId is a required property to assign the call to a specific user. name is a recommended field that helps identify the event characteristics but not required. An example server-side call:

POST api.getstories.io/v1/events/
Params: {
  user_id: "some_user_id", //Segment’s userId
  name: "Track", //Segment’s call type
  data: {
      content: "Remote Log session started" //Segment’s name
  }
}

Known & Anonymous Users

Stories does not support anonymous users at the moment. To have Stories recognize a user, you must include userId when calling identify. Otherwise, Stories won’t automatically be able to log the call under the correct user.

Merging Users

You can enable Sync Users in Stories Destination Settings. When this option is enabled, Stories will automatically merge an identified User in Segment with the corresponding Stories User and create a new User in Stories if it does not exist already. When an identify call is fired, it will also merge/update User attributes with the identify call’s traits.

An example server-side call:

POST api.getstories.io/v1/users
Params: {
    "user_id": "some_user_id", //Segment’s userId
    "name": "Han Solo", //Segment’s username
    "email": "han.solo@millenium.fa", //Segment’s email
    "phone": "+14155552671", //Segment’s phone
    "attributes": { //Segment’s Traits
        "vehicle": "Millennium Falcon",
        "latest_action": "Marry Leia"
    },
}

Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Settings

Segment lets you change these destination settings from your Segment dashboard without having to touch any code.

API Key

Paste here the Personal Access Token you created from your Stories Account > Settings > API

Sync Users

Enable this option if you want to sync your users to Stories via Segment. Only Users who have an userId will be sync. If you disable this option, Stories will only track events from already known Users and won’t merge Segment’s Traits to your Stories Users Attributes.

Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account