Creating New Functions
Last updated
Last updated
Getting Started
Use the following repo as a template for building your own Freshpaint Functions. https://github.com/freshpaint-io/functions-template.
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.
Navigate to the Functions page in Freshpaint, and provide the URL of your new repository to add your function to the Freshpaint UI:
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:
5. Complete the configuration by adding your credentials:
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.
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:
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
Each handler (onTrack
, onIdentify
, onGroup
, and onPage
) accepts two parameters:
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:
The following base properties are available on every event object regardless of the handler.
Key | Type | Description |
---|---|---|
Key | Type | Description |
---|---|---|
Parameter | Type | Description |
---|---|---|
Key | Type | Description |
---|---|---|
Key | Type | Description |
---|---|---|
Key | Type | Description |
---|---|---|
Key | Type | Description |
---|---|---|
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)
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
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.
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"
groupId
string
The ID of the group the call was for
traits
object
An object representing the group's traits
traits
object
An object representing the identified user's traits
properties
object
Any additional event properties
event
string
The name of the event
properties
object
Any additional event properties