Setting Up In-App Messages (Developer Guide)

This guide explains how to set up in-app messaging and client side tracking for Userlist. In addition to this detailed approach, you can also use one of our integration libraries that does most of the heavy lifting for you.

Language / Framework Links
Ruby Documentation, Repository
Ruby on Rails Documentation, Repository

We're continuously adding libraries for more languages. If your language or framework isn't listed yet, please follow the guide below.

Adding the JavaScript snippet

In order to use both in-app messages and client side tracking, you have to include a small JavaScript snippet in your application's layout for signed in users.

<script>window.userlist=window.userlist||function(){(userlist.q=userlist.q||[]).push(arguments)};</script>
<script async data-userlist="insert-generated-user-token-here" src="https://js.userlist.com/v1"></script>

Please note the data-userlist attribute on the second script tag. You have to pass a generated user token in here. This is a unique, signed token that authenticates the current user with Userlist's servers. This ensures that only this particular user's record can be updated and that they are the only ones who can read the messages intended for them.

Generating user tokens

The user token has to be generated on the server side. This ensures that your Push Key stays secret and nobody else can issue valid user tokens.

The user tokens are JSON Web Tokens (JWT), signed using your application's Push Key.

They require two claims in the payload. Specifically, that's sub (the user's unique identifier) and exp (the token's expiration time). In addition you must provide the kid (our Push Id in the token's header).

There are JWT libraries for almost all programming languages. Nonetheless, the process to generate the tokens is fairly simple, even without a dedicated library.

Here's an example showing how to generate a token using Ruby and its standard library.

require 'json' 
require 'openssl'
require 'base64'

# Url safe Base64 encoding without a trailing =
def base64(string)
   Base64.urlsafe_encode64(string).tr('=', '')
end  

# Generate a JSON string from the given hash 
def json(hash)
   JSON.generate(hash)
end

# HMAC signature using the SHA256 algorithm 
def hmac256(data, key)
   digest = OpenSSL::Digest.new('SHA256')
   OpenSSL::HMAC.digest(digest, key, data)
end

push_key = 'EqNgYUpW3oURUGMMU8IDnSWy4SwTLs0p' # Your applications's Push Key
push_id  = 'OMNfBvInB8g5AZbwnpiTymlccEYm6nLc' # Your applications's Push Id
payload = {
   sub: 'user-1', # The user's unique identifier
   exp: Time.now.to_i + 300 # The expiration time as unix timestamp in UTC
}

header = {
   kid: push_id,
   alg: 'HS256'
}

encoded_header = base64(json(header))
encoded_payload = base64(json(payload))
encoded_header_and_payload = "#{encoded_header}.#{encoded_payload}"

encoded_signature = base64(hmac256(encoded_header_and_payload, push_key))

token = "#{encoded_header}.#{encoded_payload}.#{encoded_signature}"

Client side tracking

After adding the tracking script including the generated user token, you're all set to send in-app messages. In addition, the tracking script also allows you to update the user's properties and to track custom events in the client's browser. See this article for the detailed instructions. Please ensure that those calls are made after the included tracking script, either by placing these calls below the script tags in your HTML or by using the page load event to delay execution.

Can I use my Segment snippet?

If you're using our Segment integration, you might be wondering whether their JavaScript snippet will work for sending in-app messages via Userlist. The short answer is no: you have to include the Userlist snippet directly.

Still need help? Contact Us Contact Us