Creating New Functions

Getting Started

1. Use the following repo as a template for building your own Freshpaint Functions. https://github.com/freshpaint-io/functions-template.

2. Create a new repository from this template, implement the methods in index.js, and configure your function settings in config.json. Additional configuration options are provided below.

3. Navigate to the Functions page in Freshpaint, and provide the URL of your new repository to add your function to the Freshpaint UI:

Adding a new function

If you attempt to create a new function that uses a private GitHub repo, a request to set up GitHub OAuth and install the Freshpaint GitHub app will appear. Follow the provided steps to allow your function to be added:

4. With your function now added, navigate to Functions under Destinations, to complete the configuration:

Configuring an existing function

5. Complete the configuration by adding your credentials:

Completing function configuration.

Your function is now configured and available as a destination. To send data to this Function, enable it in the same way that existing destinations are enabled on the events page.

Note on Backfills: There is no need for any additional backfill-specific configuration. You can rerun all events through the same functions code, as long as the endpoints you're already using can handle the added volume.

Function configuration

You can provide an optional configuration file config.json in your function's GitHub repository. The file should include a JSON object with the following fields:

Key	Type	Description
configFields (optional)	ConfigFields (see below)	Configurable settings
configName (optional)	string	The name to show when a destination or source is configured from the function
configHelp (optional)	string	A description of how to correctly configure the function, shown when a user is setting up a source or destination from the function
supportsTrack (optional)	boolean	Whether this function supports event tracking (default: true)
supportsCohorts (optional)	boolean	Whether this function supports cohorts as user properties sent to onIdentity (default: true)
supportsBackfill (optional)	boolean	Whether this function supports backfills of historical events (default: true)

Config Fields

Key	Type	Description
key	string	The key on the settings object sent to the function
name	string	The human-readable name of the field shown in the UI
required	boolean	Whether this field is required for the config to be valid
description	string	Description of the field shown in the UI
sensitive	boolean	Whether the field should be treated as sensitive
type	string	The type of the field (see below)
options	{"value": string, "label": string}	For select and radio, the options available to the user. value is passed in the settings object, label is shown to the user configuring the function.
defaultValue	type	The default value

Types of config fields

There are several different types you can use for your config field

• string

• boolean

• number

• list - A list of strings

• select - A dropdown menu

• radio - A set of radio buttons

Writing your function

Each handler (onTrack, onIdentify, onGroup, and onPage) accepts two parameters:

Parameter	Type	Description
event	object	The event data. See Event Format for details
settings	object	The configuration fields as specified in your config.json file, with the configuration values you've configured per-environment.

Event Format

The format of the event argument passed to your event handlers differs slightly depending on which handler (onTrack, onIdentify, onGroup, and onPage) is being invoked. Details about the shape of the object can be found below:

• Base properties present on all event objects

• #additional-event-object-properties-ongroup

• #additional-event-object-properties-onidentify

• #additional-event-object-properties-onpage

• #additional-event-object-properties-ontrack

Base properties present on all event objects

The following base properties are available on every event object regardless of the handler.

Key	Type	Description
type	string	The type of the event Example: "track", "identify", "page", or "group"
messageId	string	Unique id identifying this event
anonymousId	string	The ID of the device the identify call was performed on.
userId	optional string	An identifier that uniquely identifies the user that performed the event (usually email address)
context	object	An object describing the context that created this event
timestamp	string	The time the event occurred, formatted via RFC3339. Example: "2022-08-08T17:15:45Z"

Additional properties: onGroup

Key	Type	Description
groupId	string	The ID of the group the call was for
traits	object	An object representing the group's traits

Additional properties: onIdentify

Key	Type	Description
traits	object	An object representing the identified user's traits

Additional properties: onPage

Key	Type	Description
properties	object	Any additional event properties

Additional properties: onTrack

Key	Type	Description
event	string	The name of the event
properties	object	Any additional event properties