Customize streaming payloads with FreeMarker
이 페이지는 아직 귀하의 언어로 번역되지 않았습니다. 현재 작업 중이므로 곧 다시 확인해 주십시오.
Amplitude streaming transformations use FreeMarker (FTL) templates to reshape an event payload before Amplitude sends it to a destination. This reference covers the template syntax. For when and how to apply a custom FTL template, refer to Streaming transformations.
Event streaming destinations that expose a custom payload editor use Apache FreeMarker (FTL) to turn the Amplitude event into the JSON body your destination expects. The editor in the connector builder provides autocomplete, hover documentation, and inline validation for the fields and helpers below. For the FreeMarker language itself, refer to the guide to creating templates.
The input object
input is the event (or user) Amplitude forwards. Access its fields with dot notation, wrapped in ${ } to output the value:
"${input.user_id}"
"${input.event_type}"
"${input.event_time}"
Commonly available fields include event_type, user_id, device_id, time, event_time, session_id, platform, event_properties, user_properties, group_properties, and groups, plus any transformations you select (derived_properties, lookup_properties). For the complete shapes, refer to the event format and user (Identify) format.
Fields aren't guaranteed
input fields depend on how each user instruments events, and a selected event property might not be present on every event you stream. Reference fields defensively (refer to Handle missing fields), and keep required-field usage to common fields like user_id, event_type, and event_time. The payload editor flags a referenced property that isn't present on all of the events you selected.
Dot and bracket notation
Use dot notation when a property name is a valid identifier, and bracket notation when the name contains spaces or other special characters:
${input.event_properties.plan}
${input.event_properties["Plan Type"]}
Handle missing fields
Because fields aren't guaranteed, guard against missing values:
??tests whether a value exists:<#if input.user_id??>…</#if>.!supplies a default when a value is missing:${input.user_properties.email!}(empty string) or${input.revenue!0}.
{
<#if input.user_id??>
"external_id": "${input.user_id}",
</#if>
"email": "${input.user_properties.email!}"
}
Useful built-ins
FreeMarker built-ins (?name) transform values. Common ones for JSON payloads:
| Built-in | Use |
|---|---|
?c | Format a number for computers, with no locale grouping or scientific notation. Use for numeric JSON values: ${input.revenue?c} |
?json_string | Escape a string for safe use inside a JSON string: "${value?json_string}" |
?keys | Get an object's keys to iterate with <#list> |
?is_number, ?is_boolean, ?is_string | Test a value's type before serializing it |
Iterate over properties
Use <#list> with ?keys, and <#sep> to place commas between items only:
"user_properties": {
<#list input.user_properties?keys as key>
"${key}": ${UtilClass.toJsonString(input.user_properties[key])}<#sep>,</#sep>
</#list>
}
Helper methods (FtlUtils)
Amplitude exposes helper methods for serializing values and other common transforms, so you don't have to hand-write the logic. Assign the helper once at the top of the template, then call its methods:
<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
"user_properties": ${UtilClass.toJson(input.user_properties)}
}
| Method | Returns | Description |
|---|---|---|
toJson(value) | string | Serializes a value to JSON. Maps, lists, and JSON values become JSON; scalars become a quoted JSON string (for example, 42 becomes "42"). |
toJsonString(value) | string | Alias of toJson. |
dateStringToIso(dateTime) | string | Converts an Amplitude datetime string to ISO 8601. |
dateStringToEpochSeconds(dateTime) | number | Converts an Amplitude datetime string to epoch seconds. |
dateStringToEpochMillis(dateTime) | number | Converts an Amplitude datetime string to epoch milliseconds. |
epochSecondsToIso(seconds) | string | Converts epoch seconds to ISO 8601. |
epochSecondsTextToIso(text) | string | Converts epoch seconds provided as text to ISO 8601. |
epochMillisToIso(millis) | string | Converts epoch milliseconds to ISO 8601. |
isValidEmail(value) | boolean | Returns whether the value is a valid email address. |
sha256(value) | string | Returns the SHA-256 hash of the value. If the value is already a 64-character hash, returns it unchanged. |
cleanJsonPropertyName(name) | string | Replaces whitespace with underscores and removes other non-alphanumeric characters. |
getDisjointMap(source, filter) | map | Returns the entries of source whose keys aren't present in filter. |
Destination-specific helpers
Some destinations provide additional helper methods tailored to that destination. You can use those helpers only in that destination's template.
Examples
Each example shows the input event Amplitude forwards, the template you write, and the result Amplitude sends to your destination.
Simple: rename and pick fields
Map a few input fields into the shape your destination expects.
Input event:
{
"event_type": "Song Played",
"user_id": "user-123",
"event_time": "2024-01-15T09:30:00.000",
"event_properties": {
"song_id": "abc-987"
}
}
Template:
{
"external_id": "${input.user_id}",
"name": "${input.event_type}",
"song": "${input.event_properties.song_id}"
}
Result:
{
"external_id": "user-123",
"name": "Song Played",
"song": "abc-987"
}
Complex: guards, bracket notation, and iteration
Guard an optional field with ??, read a property whose name has a space with bracket notation, format a number with ?c, and serialize all user properties by looping with <#list>, emitting numbers and booleans raw and everything else through toJsonString.
Input event:
{
"event_type": "Purchase Completed",
"user_id": "user-123",
"revenue": 12.5,
"event_properties": {
"Item Name": "Pro Plan"
},
"user_properties": {
"email": "alex@example.com",
"plan": "pro",
"age": 30
}
}
Template:
<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
"event": "${input.event_type}",
<#if input.user_id??>
"user_id": "${input.user_id}",
</#if>
"item": "${input.event_properties["Item Name"]}",
"revenue": ${input.revenue?c},
"traits": {
<#list input.user_properties?keys as key>
<#assign value = input.user_properties[key]>
"${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#sep>,</#sep>
</#list>
}
}
Result:
{
"event": "Purchase Completed",
"user_id": "user-123",
"item": "Pro Plan",
"revenue": 12.5,
"traits": {
"email": "alex@example.com",
"plan": "pro",
"age": 30
}
}
이 내용이 도움이 되었나요?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.