Integration Guide

In this article, you’ll learn how to get your customer data flowing into our system: your list of users, their properties, and information about events (activities) they’re performing inside your app.

When you sign up for a new Userlist account, your list of users is blank. User profiles will start appearing there once you start pushing data for each individual user. When that happens depends on how your developer implements the integration. For example, the Rails library has an import task that gets all users into the system at once (more about that below).

Alternatively, Segment users can set up their integration in a few clicks. View this guide for instructions on Segment.

How behavior tracking works

You can track user behavior by sending us properties and events.

Properties represent the current state of the user and doesn’t have a temporal aspect — we only store the latest version. One of the properties might have changed in the past, but you cannot tell just by looking at it. User properties include things like their name, company role, their current payment plan, and anything else you prefer to track — like total number of created tasks (in a project management app for example).

Events are composed of an event name, a timestamp to describe when the event occurred, a set of additional properties (specific to the event type), and a user that triggered that event. Events are important activities performed by the user inside your application. E.g. in a project management app, events might include things like completed a task, created a new project, etc.

In addition to custom events you send us from your application, Userlist automatically records events that happen inside our system (like when users open a message, click a link, join a segment, etc.). So you don’t have to worry about tracking these things yourself.

Setting up the integration

Integrating Userlist into your application is done by sending user data and events into the system via our JSON-based Push API or via one of our native integrations. We also offer libraries for some frameworks and languages that help with the integration:

Language / Framework	GitHub
Ruby	https://github.com/userlist/userlist-ruby
Ruby on Rails	https://github.com/userlist/userlist-rails
JavaScript	https://github.com/userlist/userlist-javascript
PHP	https://github.com/userlist/userlist-php

Client-side tracking

In addition to server-side tracking, Userlist also allows client-side tracking — via the same tracking script that powers in-app messages. See these articles for details:

• Setting Up In-App Messages — how to add a JavaScript snippet and generate user tokens
• Client-Side Tracking — how to use that script for sending user events and properties

Best practices for a successful integration

A successful integration isn’t just a matter of technical setup. It’s equally important to be strategic and consistent in your user tracking — so that the data reflects your business goals and makes sense to all team members down the road.

Before you start the integration process, you need to make the following decisions:

1. Figure out what properties and events need to be tracked. As a Userlist customer, you will be offered a free 60-minute roadmapping session where we develop the tracking plan together based on your unique customer journey.
2. Choose a naming convention and use it to document these properties and events before you implement them in code.

For further reading, we recommend this article on naming conventions published by the team at Segment.

Here are some of our recommendations:

• Use a framework for naming events (e.g. Object-Action framework)
• Track time instead of boolean — this will enable you to segment more meaningfully and send better communications, since you know when the user performed a certain event last time (as opposed to a boolean)
• For dates we recommend to use an _at suffix (e.g. trial_expires_at)
• Be consistent with vocabulary and phrase structure. Our recommendation for event names is resource name + verb in past tense, e.g. message_sent, template_created
• Be consistent with capitalization and characters between words — e.g., created-project vs created_project

What exactly should I track?

You don’t need to reinvent the wheel. Sure, many properties are specific to your industry, but many of them are similar to most SaaS companies. To help you with planning, we created a set of free planning worksheets (12 pages, printable PDF) to use as a baseline.

We strongly recommend to take advantage of your free roadmapping session. The scheduling link should be in your inbox among other onboarding emails. Or please reach out to support if you didn’t receive it.

We will help you to figure out the most important properties and events to track, and how to name them. This will save you a lot of time and effort in the long run.