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

identify calls are 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

page and screen calls are 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 is 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

track calls are 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 is 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

Stories automatically merges identified Users in Segment with their corresponding Stories User and creates a new User in Stories if it does not exist already. When an identify fires, it merges/updates 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"
    },
}

Sync Users

When you setup your Stories Destination in Segment, your users automatically sync to Stories. Please note that only Users who have a userId in Segment are synced, Stories does not support anonymous users yet. Users are updated by identify events from Segment.

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

This page was last modified: 24 Mar 2020

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