Avo Functions in TypeScript

6 minute read

Platforms

Avo can code generate Avo Functions in TypeScript targeted at the following platforms

  • Web
  • React Native
  • Node.js

Quickstart

Avo functions usage consists of 4 steps.

Step 1. Include the Avo file

Pull the generated code with the Avo CLI

To get the Avo generated TypeScript file you must be a member of an Avo workspace with a TypeScript source. Ask for an invite from a colleague or create a new workspace

Terminal
Copy
$
$
$
npm install -g avo
avo login
avo pull --branch my-branch-name

Learn more about the CLI here.

You can also download the file manually from your Avo workspace.

Step 2. Initialize Avo

Import Avo from the generated file and initialize it by calling the initAvo method before tracking

TypeScript
Copy
1
2
3
4
5
6
7
8
import Avo from './Avo';
Avo.initAvo(
{ env: Avo.AvoEnv.Dev },
[systemProperties],
[destinationOptions],
[customDestination],
);

The actual parameters depend on your tracking plan setup, see the parameters explanation in the reference below.

Step 3. Call Avo functions to track your product usage

Every event in your tracking plan, marked with the "Implement with Avo" checkbox, gets a function in the generated code, named according to the event name, in camelCase.

For example, if you have a "Signup Start" event defined like this in Avo:

Event 'Signup Start' defined in Avo with referral string property and implement with Avo check

You'll be able to call it like this from the generated code

TypeScript
Copy
1
Avo.signupStart({ referral: 'direct' });

Notice, that you are not passing the System property with the call. System properties are defined on the init step and then automatically included with all events. You can update the system properties with setSystemProperties function.

Step 4. Verify the implementation

Use the Implementation status in your Avo workspace and the visual debuggers to verify that your implementation is correct.

Reference

initAvo

TypeScript
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Avo.initAvo(
options: {
env: AvoEnv;
[webDebugger?: boolean];
[strict?: boolean];
[noop?: boolean];
[reportFailureAs?: 'error' | 'warn' | 'log'];
[inspector?: AvoInspector];
[avoLogger?: AvoLogger];
},
[systemProperties: {
systemProperty0: number;
systemProperty1: boolean;
...}],
[destinationOptions: any],
[CustomDestDestination: CustomDestination])

Initializes Avo, needs to be called before the tracking methods. This method will initialize the SDKs for all destinations that are managed by Avo, and call the make(env) callback in the provided custom destinations.

Arguments

options: {env, [noop], [strict], [avoLogger], [inspector], [mobileDebugger]}

  • env: AvoEnv, can be set to dev, prod and staging.
  • `[webDebugger]: optional bool, for optional Avo Web Debugger instance
  • [strict = true]: bool defaulting to true, if true, Avo will throw an exception when it detects a tracking problem in development or staging. Note that the strict flag is ignored in production.
  • [noop = false]: bool defaulting to false, if true, Avo won't make any network calls (no tracking) in development and staging environments. Note that the noop flag is ignored in production.
  • `[reportFailureAs]: optional, can be set to error, warn and log. Decides the log level of reports for failures.
  • [inspector]: optional Avo Inspector instance. If you use Avo Inspector pass it here to make the Avo functions automatically report the invocations to the Avo Inspector.
  • [avoLogger]: optional custom implementation of the logger. Can be used to disable logs. Find the code snippet here.

systemProperties: an object where each field represents a system property in your tracking plan. When you define system properties in your Avo workspace you set name and type - the fields of this object are named the same as system properties, in camelCase, and you should provide corresponding types, can be string, int, long, float, bool, array, object and any.

destinationOptions: {[segmentDestinationName], [anotherSegmentDestinationName], [amplitudeDestinationName], [mixpanelDestinationName]}. Keys of this objects are the camelCase versions of your destinations in the Avo UI.

  • mixpanelDestinationName: optional object, if you use Mixpanel destination managed by Avo, this object will be passed to mixpanel.init(apiKey, options) as the second parameter, options
  • amplitudeDestinationName: optional object, if you use Amplitude destination managed by Avo, this object will be passed to amplitude.init(apiKey, null, options) as the third parameter, options
  • segmentDestinationName: optional object, if you use Segment destination managed by Avo, this object will be passed to analytics.load(apiKey, options) as the second parameter, options

customDestination: CustomDestination, required if given source has a custom destination set up in Avo. Otherwise ignored.

Custom destination interface format:

TypeScript
Copy
1
2
3
4
5
6
7
8
{
make?: function (env: AvoEnv): void,
logEvent?: function (eventName: string, eventProperties): void,
setUserProperties?: function (userId: string, userProperties): void,
identify?: function (userId: string): void,
unidentify?: function (): void,
logPage?: function (pageName: string, eventProperties): void
};

Read more about custom destinations here.

setAvoLogger

TypeScript
Copy
1
Avo.setAvoLogger(avoLogger);

This method allows you to provide custom implementation of the logger used by the Avo Functions, same as the avoLogger parameter in the initAvo call. Can for example be used to disable logs or change which logging method is used.

Arguments

avoLogger: custom implementation of the logger. Find the code snippet here.

setSystemProperties

TypeScript
Copy
1
Avo.setSystemProperties(systemProperties);

A method to update system properties. If you provide undefined values here corresponding properties won't be updated

Arguments

systemProperties: an object where each field represents a system property in your tracking plan. When you define system properties in your Avo workspace you set name and type - the fields of this object are named the same as system properties, in camelCase, and you should provide corresponding types.

Event tracking functions

TypeScript
Copy
1
Avo.yourEventName(properties: { [eventProperty0], [eventProperty1], ..., [userProperty0], [userProperty1], ..., [groupType0GroupId], [groupType1GroupId], ..., [groupProperty0], [groupProperty1], ..., [userId_], [anonymousId_], [segmentContext_] })

Every event you define in your tracking plan in Avo gets a function named after the event in camelCase. The arguments of the function depend on how it's defined in your tracking plan

Arguments

eventProperty: type defined in the Avo tracking plan, can be string, int, long, float, bool, array, object and any. Every event property attached to the event in the Avo UI gets a corresponding argument. The argument key is camelCase version of the property name defined in the Avo UI. Pass the value of the property to track here.

userProperty: type defined in the Avo tracking plan, can be string, int, long, float, bool, array, object and any. Every user property attached to the event in the Avo UI gets a corresponding argument. The argument key is camelCase version of the property name defined in the Avo UI. Pass the value of the property to update here.

groupTypeGroupId: string, if this event has group type attached in the UI, you'll provide the group id here. The argument key is camelCase version of the group type defined in the Avo UI with the "GroupId" suffix. E.g. if the event has "company" group type, the property will be celled "companyGroupId" and you would provide the company name.

groupProperty: type defined in the Avo tracking plan, can be string, int, long, float, bool, array, object and any. Every group property attached to the event in the Avo UI with the "Group Update" action gets a corresponding argument. The argument key is camelCase version of the property name defined in the Avo UI. Pass the value of the property to update here.

userId_: string, used to connect event to specific user Web and React Native: Added if the event has the Identify User action Node.js: added to all events, you have to either provide it or the anonymousId_

Additional arguments

anonymousId_: string, Node.js only, this argument is automatically added if corresponding setting is enabled, used to track anonymous users

segmentContext_: object, Node.js only, passed down to Segment as the Segment context, e.g. segment.track({..., context: context})

Destinations

You can send your data using the Avo generated TypeScript code to any data destination that accepts custom events, including:

  • Amplitude
  • FacebookAnalytics
  • FullStory
  • Mixpanel
  • Mixpanel
  • Permutive
  • Segment
  • Snowplow
  • ZendeskConnect
  • Adobe Analytics
  • Apptelemetry
  • Rudderstack
  • Freshpaint
  • Posthog
  • Google Analytics 4 / Firebase Analytics
  • Heap
  • Keen
  • Kissmetrics
  • LaunchDarkly Events
  • Pendo
  • Fivetran
  • AppsFlyer
  • Braze
  • Intercom
  • A home made SDK
  • Internal API