Sending User Properties Guide (technical)

This article is intended for developers implementing Appcues. See the User Properties Overview for a higher level explanation.

Required properties

The only requirement is to send a user ID as the first argument to Appcues.identify().

Recommended properties

See the  User Properties Overview for recommendations.

Adding User Properties

If you haven't installed Appcues, adding User Properties is covered in the  Installation Guide (technical) and you should start there.

If Appcues is installed, open the file that contains the Appcues.identify() call. It should look something like this: 

Add additional properties in the existing User Properties section. 

For code template help, go to the  Installation page

Select "I Want to Install Appcues Myself":

Choose the appropriate framework: 

In the "Identify the User" section, copy / follow the syntax from the "Additional user properties":

Formatting data

Generally, you'll want to follow these three guidelines when preparing data to send to Appcues:

1. Keep property names simple and understandable.

The Appcues UI will try to reformat the property name into something readable, so a property like "days_since_signup" becomes "Days Since Signup" and "planName" becomes "Plan Name". To make things easier on your non-technical colleagues, send in property names that are simple and clear. Avoid names like, "property_1" or "base64UUID" unless that's a well-known label among your team.

2. Don't reformat types.

Send numbers as numbers, strings as strings, etc. Appcues uses type inference to match targeting criteria, so you don't need to think about types. This is really important when doing comparison, since the number 10 is greater than the number 2, but the opposite is true if those values are converted to strings.

In the same vein, if a value is undefined or null, either don't send it to Appcues, or send it as null. Do not send an empty string for any non-existent value.

Lastly, make sure that each user property has a consistent type. As an example, "signup_date" could either be sent as a timestamp (number) or as an ISO date (string). Whichever you choose, make sure to be consistent every time that value is sent to Appcues. Inconsistency could result in over- or under-targeting content to.

Appcues uses UNIX Epoch timestamps for dates and times internally.

3. Only send simple (primitive) values (numbers, strings and booleans).

Appcues targeting can only operate on numbers, strings and booleans. You can send complex objects in your Appcues.identify() call, but they will be silently ignored. We don't recommend sending objects to Appcues as a user property.

If information in those objects are important, we recommend flatting the object or reducing the object to a single value before calling Appcues.identify(). For example, if you had a user property called "invoices" that was a collection of billing information, you could reduce that into the following useful properties:

<script>
var invoices = user.invoices || [];
var totalInvoices = invoices.length;
var lastInvoiceDate = (invoices[0] || {}).created_at;
Appcues.identify(user.id, {
  name: user.name,
  email: user.email,
  totalInvoices: totalInvoices,
  lastInvoiceDate: lastInvoiceDate
})
</script>

Still need help? Contact Us Contact Us