Vero Developer Guide

Last updated: 11 February 2025

Overview

Vero platform overview

Vero is a customer engagement platform for product and product marketing teams at B2C and product-led B2B businesses. Vero works best for post-signup use cases where you have a solid, clear "identifier" for the users of your software.

We currently offer two versions of our software:

Vero Cloud. A traditional SaaS product. Send Vero data about your users and their actions ("events") using our Track REST API. We store this data on your behalf in our cloud (the "Vero data store" in the diagram above) and enable you to create segments and workflows using this data in the Vero Cloud UI. Works with RudderStack, Segment, Hightouch, Census and other integrations.
Vero Connect. A "warehouse-native" version of Vero. Vero Connect does not store any of your user or user activity ("event") data. Instead, audiences are loaded on-demand from your data warehouse (e.g., Snowflake, Redshift, etc.) The Vero Connect UI enables you to create campaigns using these audiences.

The Track REST API is used only with Vero Cloud. The Application REST API is designed to work with both versions of Vero.

We want your feedback! The Application REST API is currently in preview and we want your feedback. Whilst is not available for public use (there is no authentication mechanism) we would love to hear how you will use it when released. Send your feedback to support@getvero.com.

Platform Core Concepts

Vero's API is built around these core concepts.

User

A User represents a user of your product. Vero is best suited to post-signup use cases where you have a unique, database identifier for each of your users.

You can use Vero for pre-signup use cases. Users can be tracked into Vero with an email address and no id, enabling you to alias and update a user's id once they sign up. Similarly, you can generate random, unique id values for non-signed sessions and alias these once a user logs in.

Event

An Event represents an action taken by a User at a specific point in time. Examples of common events include Signed up, Clicked Button, Campaign Created, Order Completed. Events represent the historical log of everything a user has done. Events typically relate to a User and some other object, e.g., an Order, a Campaign, etc.

Campaign

A Campaign links three things together:

A Trigger.
An Audience.
A Message.

Triggers include a single, scheduled time, a recurring schedule and event triggers.
You don't need a Campaign to send a Message. You can send a Message directly via the API if you'd like to.
Reports are only aggregated for Campaigns. We record all the opens/clicks/etc. for every Delivery and Message record but Campaigns are a way of reporting on a group of Messages together.

Trigger

A Trigger defines how a Campaign is initiated. Trigger types include:

immediate which sends the campaign as soon as it is launched.
scheduled which runs at a specific time.
recurring which runs on a cron schedule.

We're building our new triggers such as api, event and more.

Audience

An Audience represents a list of one or more users.

Message

A Message represents a templated version of what will be sent to an Audience. A Message is designed to be multichannel and contains an array of Content objects: one for each channel the message may be sent to. Vero currently supports email, push Content and we are working to add sms and http.

Content

The Content object includes all of the fields required to successfully deliver a message on a specific channel. For example, email always requires a to, subject and body field.

SDKs

Vero offers several SDKs for the most various programming languages and environments. The GitHub repository for each library contains more information on setup and use.

JavaScript/TypeScript SDK
Ruby
PHP
iOS (legacy)

Don't see your language of choice? We also have an active community who has built Vero SDKs for other languages. Please see the corresponding GitHub repositories for more information. A big shout-out to all of our customers who have contributed libraries they've written! Thank you.

Please note that the community-supported libraries may not be updated regularly and Vero provides no guarantee or warranty for their performance or reliability.

JavaScript SDK

You can embed Vero's tracking code in your website using our JavaScript/TypeScript SDK. Below shows how you can get started.

This SDK is also available as an NPM package for advanced use cases (e.g., integrating in React or Node.js applications). Please refer to the package's README for more information.

Install the SDK

You will need the tracking API key to set up the SDK. You can find your API key on the Settings page of your Vero account.

Then, insert the following code into your <head> section of every HTML document that you want to track events on, replacing <YOUR_TRACKING_API_KEY_HERE> with your API key.

<script src="https://cdn.jsdelivr.net/npm/@getvero/tracking@latest/dist/index.window.js"></script>
<script>
    vero.tracker.init({
        trackingApiKey: "<YOUR_TRACKING_API_KEY_HERE>"
    })
</script>

Identify a user

When a user logs in, you should call the user.identify method. Both the id and email fields are required.

vero.tracker.user.identify({
    id: "<USER_ID_HERE>",
    email: "<USER_EMAIL_HERE>"
})

This will add or update a User to your Vero data store.

You can also attach additional channels or add additional fields to the User profile:

vero.tracker.user.identify({
    id: "<USER_ID_HERE>",
    email: "<USER_EMAIL_HERE>",
    channels: [
        {
            type: "push",
            address: "<PUSH_TOKEN_HERE>",
            platform: "android"
        }
    ],
    data: {
        first_name: "<FIRST_NAME_HERE>",
        last_name: "<LAST_NAME_HERE>"
    }
})

Track an event

An Event represents a user action in your application. For instance, when a user takes a specific action or changes state.

vero.tracker.event.track({
    eventName: "viewed product",
    data: {
        product_name: "Red T-shirt",
        product_url: "https://www.example.com/products/red-t-shirt",
    }
})

You must call user.identify prior to calling event.track, unless you supply an identity object to the method. Once you call user.identify, the SDK will automatically identify the user and store the id and email in the browser's local storage for future requests.

You can also pass in an optional extras object as outlined in the Track REST API:

vero.tracker.event.track({
    eventName: "viewed product",
    data: {
        product_name: "Red T-shirt",
        product_url: "https://www.example.com/products/red-t-shirt",
    },
    extras: {
        source: "My application",
        createdAt: "2023-05-30T04:46:31+0000",
    }
})

Unidentify a user

If a user logs out, you should call the user.unidentify method so future events will not be accidentally associated with the user.

vero.tracker.user.unidentify()

Advanced usage

Alias/merge a user

vero.tracker.user.alias({
    newId: "<NEW_USER_ID_HERE>"
})

Add/remove tags

vero.tracker.tag.edit({
    add: ["<TAG_NAME_HERE>"],
    remove: ["<TAG_NAME_HERE>"]
})

Unsubscribe

vero.tracker.user.unsubscribe()

Resubscribe

vero.tracker.user.resubscribe()

Delete a user

vero.tracker.user.delete()

Ruby, PHP and others

Please refer to the respective SDK GitHub repositories (see SDKs above) for how-tos on using the Ruby, PHP and community-supported SDKs.

Legacy `m.js` JavaScript SDK

Prior to 2025, Vero had a legacy JavaScript SDK that was used to interact with the Vero Track API. We recommend using the JavaScript/TypeScript SDK instead, especially for new projects. However, the legacy m.js SDK is still available for use and will continue to be supported.

m.js documentation

Initialize the SDK

Before you can use any of the functions available in the Vero JavaScript SDK, you must first initialize the SDK. To do so, place the following JavaScript on your website, typically in the <head> section of your HTML. We recommend including this on every page.

Insert an active Vero API key. You can manage your API keys under Settings in your Vero Cloud account.

var _veroq = _veroq || [];
_veroq.push(["init", {api_key: "INSERT_API_KEY"}]);

(function () {
    var ve = document.createElement("script");
    ve.type = "text/javascript";
    ve.async = true;
    ve.src = "//d3qxef4rp70elm.cloudfront.net/m.js";
    var s = document.getElementsByTagName("script")[0];
    s.parentNode.insertBefore(ve, s);
})();

Add or update a user

When adding a User using the JavaScript SDK either an id or email value are required. All other attributes are optional and customizable. In this example we're passing a value for the first_name, last_name and subscription properties.

_veroq.push([
    "user",
    {
        id: "123",
        email: "damienb@getvero.com",
        first_name: "Damien",
        last_name: "Brzoska",
        subscription: "medium",
    },
]);

Track an event

An Event represents a user action in your application. For instance, when a user takes a specific action or changes state.

When tracking an Event using the JavaScript library you do not need to pass an identity object as outlined in the Track REST API. Instead, you must make a call to the identify SDK method outlined above. A cookie is then stored and this identity is used by the SDK to form the full API request for you.

_veroq.push([
    "track",
    "viewed product",
    {
        product_name: "Red T-shirt",
        product_url: "http://www.yourdomain.com/products/red-t-shirt",
    },
]);

When tracking an Event, the JavaScript SDK supports passing the optional extras object as outlined in the Track REST API.

_veroq.push([
    "track",
    "viewed product",
    {
        product_name: "Red T-shirt",
        product_url: "http://www.yourdomain.com/products/red-t-shirt",
    },
    {
        source: "My application",
        created_at: "2024-08-01 10:05",
    },
]);

Alias/merge a user

The alias method is used to merge two user identities, merging two sets of user data into one. This is an advanced method and may have unintended consequences. Please get in touch if you have questions regarding its usage

_veroq.push([
    'reidentify', {
        '456', // The new user ID
        '123'// The old user ID
    }]);

Add/remove tags

Tags are one way to assign states or temporary attributes to users. Whilst tags are a first-class citizen in Vero we do eventually envision sunsetting them in favour of basic user attributes. For new use cases we encourage you to simply update a user attribute rather than use a tag.

_veroq.push([
    "tags",
    {
        id: "123",
        add: ["prospect"],
        remove: ["customer"],
    },
]);

Unsubscribe and resubscribe

To unsubscribe or resubscribe a user, supply the User's id. In this example, 123 is the id.

_veroq.push(["unsubscribe", "123"]);

_veroq.push(["resubscribe", "123"]);

Delete a user

Users can't be deleted via the JavaScript SDK at this time.

Webhooks

Read more on how to set up Vero's webhooks.

Webhooks can be configured in the Vero Cloud UI. To configure webhooks in Vero Connect, please email support via support@getvero.com.

Configuring Delivery Providers

You can configure Vero to send your email and push messages via multiple providers.

Email

By default Vero will send emails using a shared domain and shared IP addresses. You can configure a custom domain so that your emails are signed by yourdomain.com. You can also configure Vero to send emails via your own account with Sendgrid, Mailgun, Mailjet and more. Read more on configuring a custom email domain.

iOS and Android Push

To send iOS and Android push messages you must configure your application to handle incoming push messages. Vero does not currently provide an iOS or Android SDK but does provide an explanation and examples of the minimum code required to handle push messages. Read more in our Push Notification Integration Guide.

Vero Developer Guide

Overview

Platform Core Concepts

User

Event

Campaign

Trigger

Audience

Message

Content

SDKs

JavaScript SDK

Install the SDK

Identify a user

Track an event

Unidentify a user

Advanced usage

Ruby, PHP and others

Legacy m.js JavaScript SDK

Webhooks

Configuring Delivery Providers

Email

iOS and Android Push

Legacy `m.js` JavaScript SDK