Start using Avo Functions

8 minute read

In this guide we'll cover all the required steps to start using Avo in your app or website, both alongside existing tracking code and SDKs and in a new project.

Integrating Avo with your app or website can begin as soon as you create an Avo account, and requires three steps:

  1. Configure Connections in your Avo workspace
  2. Install the Avo CLI
  3. Initialize Avo and send your first event

1. Configure your Avo workspace

In your Avo workspace head to the Connections tab in the left sidebar. Here we'll create a Source for our app and a Destination for every SDK we want to pass data into.

💡 What are Connections?
In Avo you define from which apps, websites and servers your data is sent (Sources) and to which SDKs and APIs the data is passed into (Destinations). In Avo the relation between Sources and Destinations are called Connections.


Configure a source

If a source doesn't already exist for your app or website, click "Add Source" to create a new Source. Give it a name and define what development platform and programming language you'll be using. This configuration is used to tailor the Avo Functions to your stack.

Source configuration
A source configuration for MyApp.com, which is a Web app written in TypeScript

Configure destinations

In Avo there are two options when it comes to destinations:

Option 1. Initialize the destination (e.g. SDK) on your own and connect Avo to it. This is what we call a Custom Destination.

Option 2. Let Avo fully manage the destination for you (everything from initializing to passing data into it).

If you already have an analytics SDK running in our app, it's initialized and already receiving data, you should go with Option 1. If you don't have any existing tracking we recommend Option 2.

Head back to the Connections tab and click "Add Destination". To configure a destination:

  1. Give the destination a name, e.g. My Analytics SDK
  2. Check the Analytics Tool drop down list. If you decided to go with Option 1, choose Custom, otherwise choose the name of your analytics tool. If you don't see the tool you need use Option 1.
  3. Enable your source for the destination (there might be a case when your programming language and platform does not support given analytics platform, in this case you would need to go with Option 1)

Note that the Production API Key and Development API Key are not required for custom destinations.

If you use multiple analytics tools, you should repeat this process and create a destination for every analytics tool.

Destination configuration
A Destination for My Analytics SDK, which is a destination used on MyApp.com


All set!

Here we've configured a Source, sending to a Custom Destination called My Analytics SDK:

Connections configuration
Our Source and Destination

Configure events

Head to the Tracking Plan tab. If no events exist in your tracking plan yet you can either import your existing tracking plan or define events in the Tracking Plan. Make sure to attach the source you'll be implementing to all events you want to implement. Learn more about attaching sources to events here.

2. Install Avo to your project

💡 How does Avo integrate with my project?
Avo code-generates a file based on the Tracking Plan in your Avo workspace. The file contains a function per each Event in the Tracking Plan that you use to send your events. We call these functions Avo Functions. Each Avo Function validates the event data before passing it forward to your Destinations.

You can think about the Avo Functions like a utility file for your analytics. It should be placed somewhere in the source code directory of your Source and checked into git. Every time the tracking plan in Avo is updated, the Avo Functions are updated.

To make the workflow of updating the Avo Functions as easy as possible we built the Avo CLI. By running avo pull the CLI will update the file containing the Avo Functions automatically.

Install the Avo CLI

Install the Avo CLI locally in your project (recommended), using NPM or Yarn:

Terminal
Copy
npm install --save-dev avo
Terminal
Copy
yarn add --dev avo

or globally on your system, using NPM or Yarn:

Terminal
Copy
npm install -g avo
Terminal
Copy
yarn global add -E avo

Authenticate the Avo CLI with your Avo user:

Terminal
Copy
avo login

Now you can pull the Avo Functions from your Avo workspace. When you run Avo pull for the first time it will also initialize Avo in your project by adding an avo.json file, containing a pointer to your Avo workspace, source and current branch. This file should be checked into git along with the Avo Functions file.

Terminal
Copy
avo pull

3. Initialize Avo and send an event

Initialize Avo

Before we can start using the Avo Functions to log events we first need to initialize Avo by calling the initAvo function exported from the file. Avo is usually initialized in the same place you initialize all your other analytics SDKs, or as soon as possible in the runtime of your app.

First we import the Avo Functions and set up the destinations.

If we are using an Avo-managed tracking destination (Option 2) all we need to do is to import the corresponding SDK.

If we are using Custom Destinations (Option 1) we define an interface for each destination, where we connect it to our analytics SDK:

TypeScript
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
import Avo from './Avo';
// An interface for your Custom Destination that you pass into initAvo():
let myAnalyticsSDKBridge = {
make: function (env) {
/*
Triggered during Avo initialization. Here you can initialize an analytics SDK with a development or production key
based on the env parameter. If analytics SDK has already been initialized you can leave this function blank.
Example: analytics.init(env);
*/
},
logEvent: (eventName, eventProperties) => {
/*
All your events are managed in the Tracking Plan in Avo. Each event gets a generated Avo Function. Avo events can
have a Log Event action attached. This callback is triggered when an Avo Function with Log Event action is called.
Here you perform the actual event tracking, calling the track/log methods of the analytics SDK. Event name and event
properties are provided as parameters.
Example: analytics.track(eventName, eventProperties);
*/
},
setUserProperties: (userId, userProperties) => {
/*
You can add User Properties to events in the Trackin Plan in Avo. When an Avo Function with attached user properties
is called, this callback is triggered. Here you would attach user properties to the currently identified user in your
analytics platform.
Example: analytics.setUserProperties(userId, userProperties);
*/
},
identify: (userId) => {
/*
You can add the Identify User action to events in the Trackin Plan in Avo. When calling an Avo Function that includes
the Identify User action you'll need to provide a user ID. Calling an Avo Function that has the Identify User action
will trigger this callback. The main use cases are signup and login. Here you would pass the user ID to the analytics
SDK for it to create a new user or attach a session to an existing user.
Example: analytics.identify(userId);
*/
},
unidentify: () => {
/*
You can add the Unidentify User action to events in the Trackin Plan in Avo When calling an Avo Function that includes
the Unidentify User action this callback will be triggered. Here you would call an analytics SDK method to detach subsequent
actions from the currently identified user.
Example: analytics.identify(null);
*/
},
};

Then we call the initAvo Function:

TypeScript
Copy
1
Avo.initAvo({ env: Avo.AvoEnv.Dev }, {}, myAnalyticsSDKBridge);

Detailed instructions on how to initialize Avo with Custom Destinations for all other programming languages and platforms supported by Avo can be found here.

Send an event

Now we're ready to start implementing reliably analytics tracking with Avo Functions. Every Event defined in our Tracking Plan on avo.app has it's own function in the Avo Functions file.

Let's say we have defined the "App Opened" event in our Tracking Plan in Avo, with two Event Properties, "Client" and "Screen Name". Here's how we would send the event using Avo Functions:

TypeScript
Copy
1
Avo.appOpened({ client: 'Web', screenName: 'Home Screen' });

On some server platforms Avo functions are async, e.g. on Node.js they return a Promise and on C# you can await on the Avo Functions

When the Avo Function is called Avo will run validation on the event properties, making sure they fit the spec defined in the Tracking Plan in Avo. Note that this validation is only run in development mode. If you are using a Custom destination Avo passes the event name and properties to the logEvent function in the Custom Destination interface defined above, otherwise it will pass the event directly to the analytics tool defined in your destination.

You can find tailor made documentation for your Avo Functions, based on your Tracking Plan, in the Implement tab in your Avo workspace.