Logic Scripts

Code
# Logic Script behavior and syntax documentation

FunnelFlux Logic Scripts are reusable routing scripts for funnel logic nodes.

A script reads visitor, request, tracking-field, visitor-tag, time, and
submitted-form context, then returns a single route key as a string.

Funnel connections leaving the logic node match the returned route key
through `connectionLogicParams.onRouteKeys[]`.

## Core format

- A Logic Script is a Go-statement snippet, not a full Go file.
- Do not include package declarations.
- Do not include imports.
- Do not include a function wrapper.
- Every execution path must return a string route key.
- Statements run top to bottom; the first `return` reached wins, so order
  your rules from most specific to most general.
- Maximum code size is `10240` bytes.

## Route-key rules

- Route keys must match `^[a-z0-9_]{1,64}$`.
- Use lowercase letters, numbers, and underscores.
- Use semantic keys such as `business_hours` or `blocked_isp`, not `a`/`b`.
- Prefer explicit string returns such as `return "us"`.
- Avoid returning a variable as a route key unless the funnel has a safe
  default connection to catch unexpected values.
- Always include a `default` return path as the final statement.

## The `default` route: what it is for

`default` is the safety net for things going wrong, not a normal business
outcome. The default *connection* in the funnel is used when:

- the code is invalid or fails to execute,
- required data is missing due to a system error (for example, IP
  geolocation failed, so `country` is empty),
- or the script returns a route key that is not connected to anything.

Because of this, you normally do **not** write explicit branches for
error-state empty values. For example, you would not add an
`if country == "" { ... }` branch — a blank country means IP resolution
failed on our side, which is an error condition, and letting it fall
through to the final `return "default"` is the correct handling.

This is different from a deliberate "matched none of my rules" outcome.
When a value resolves correctly but simply doesn't match any of your
business rules, give that its own named route (for example, `unmatched`)
rather than folding it into `default`. That keeps real traffic separable
from genuine errors in reporting and wiring.

## Funnel wiring rules

These matter when manipulating Logic Scripts inside funnels via API. If you
are only writing isolated script code, you can ignore them.

- Each connection leaving a logic node uses
  `connectionLogicParams.onRouteKeys[]`.
- Connect every route key your script can return to a destination.
- Always connect `onRouteKeys ["default"]` to a safe fallback destination.

> Builder/editor integrations can use the Assets API helper endpoints:
> `GET /v1/logicscripts/language` returns the backend-owned catalog
> (variables, helpers, operators, route-key rules, max size, templates),
> and `POST /v1/logicscripts/validate` checks a script and returns whether
> it is valid, which route keys it found, and any errors.

## Variable context

- Variables mirror how URL `{tokens}` work in the runtime routing system.
- Tokens are replaced by data resolved from the current tracked visitor.
- Geolocation values are derived from the visitor IP.
- All variables concern the specific visitor currently tracked in a funnel.
- `trackingDomain` is the custom domain used at redirect time.
- `trafficSourceID` is an internal FunnelFlux traffic source asset ID.

## Available string variables

`country`, `city`, `region`, `continent`, `timezone`, `deviceType`,
`brand`, `model`, `os`, `osVersion`, `browser`, `browserVersion`,
`mainLanguage`, `browserLanguage`, `ip`, `isp`, `connectionType`,
`mobileCarrier`, `userAgent`, `referrer`, `initialReferrer`,
`currentURL`, `trackingDomain`, `trafficSourceID`

## Available integer variables

`hour`, `minute`, `weekday`, `dayOfMonth`, `month`, `year`, `utcOffsetHours`

## Value notes

- Time variables (`hour`, `minute`, `weekday`, etc.) are UTC and refer to
  the current timestamp. For visitor-local time, use the time helpers with
  `utcOffsetHours` rather than these raw UTC values.
- `weekday` uses Go values: Sunday is `0`, Saturday is `6`.
- `month` uses Go values: January is `1`, December is `12`.
- `country` is an ISO country code such as `US` or `TH` (uppercase).
- `country` is effectively always populated for a real visitor. It is
  empty only when IP geolocation fails — treat that as an error and let it
  reach `default` (see "The `default` route").
- `continent` is a full name such as `Asia`, `Europe`, `North America`, or
  `Oceania` — not a code such as `AS` or `EU`.
- `city`, `region`, `isp`, `connectionType`, `mobileCarrier`, `deviceType`,
  `brand`, `model`, `os`, `browser`, and similar values are resolved from
  the visitor IP and user agent. When a specific value can't be determined
  they typically return the literal string `unknown`, not an empty string.
  An empty value therefore signals a resolution error — which is exactly
  what `default` is for. Do not write branches for any of these being
  blank; an unresolved IP or user agent is an error state, not a routing
  case. (If you ever need to catch a non-resolving value deliberately,
  test for `== "unknown"`, not `== ""`.)
- `referrer` is the current request referrer, falling back to
  `initialReferrer` when empty. An empty `referrer` is a normal, expected
  state (direct traffic, stripped referrer) — branch on it deliberately if
  your logic cares about it. This is the main string variable where blank
  is a real case rather than an error.
- `trafficSourceID` is an internal traffic source asset ID (roughly a
  14-character alphanumeric string). You cannot know a specific ID unless
  the user provides it. The one fixed, system-level value you can rely on
  is `organic`: organically tracked traffic always has
  `trafficSourceID == "organic"` (lowercase).
- `timezone` is a display string formatted like the public `{timezone}`
  token — `GMT+7`, `GMT-5`, `GMT+0`. Do **not** pass it to the time
  helpers; they take an integer offset, not this string.
- `utcOffsetHours` is the matching whole-hour integer offset for the same
  visitor (`7`, `-5`, `0`). This is the value you pass to `timeInRange()`,
  `timeAtOrAfter()`, `timeAtOrBefore()`, and `localDay()` for
  visitor-local time routing. You do not hardcode an offset — use this
  variable so each visitor is evaluated in their own local time.
- `mainLanguage` and `browserLanguage` reflect captured visit languages.
- In general, string variables hold the same values shown in reporting.

## Available helpers

| Helper | Returns |
| --- | --- |
| `len(value string)` | `int` |
| `trackingField(name string)` | `string` |
| `dataBuffer(name string)` | `string` |
| `hasVisitorTag(id string)` | `bool` |
| `oneOf(value string, candidates ...string)` | `bool` |
| `containsAny(value string, substrings ...string)` | `bool` |
| `timeInRange(startHHMM int, endHHMM int, utcOffsetHours int)` | `bool` |
| `timeAtOrAfter(hhmm int, utcOffsetHours int)` | `bool` |
| `timeAtOrBefore(hhmm int, utcOffsetHours int)` | `bool` |
| `localDay(utcOffsetHours int)` | `string` |
| `strings.Contains(value, substr string)` | `bool` |
| `strings.HasPrefix(value, prefix string)` | `bool` |
| `strings.HasSuffix(value, suffix string)` | `bool` |
| `strings.ToLower(value string)` | `string` |
| `strings.ToUpper(value string)` | `string` |

## Helper notes

- `oneOf()` does exact matching against many candidate values.
- `containsAny()` does substring matching against many candidate substrings.
- Both `oneOf()` and `containsAny()` accept either inline arguments or an
  expanded `[]string`:
  - inline: `oneOf(country, "US", "CA", "AU")`
  - expanded slice: `oneOf(country, tierOne...)` where
    `tierOne := []string{"US", "CA", "AU"}`
- Use `strings.ToLower()` to normalise a value once before case-insensitive
  comparisons, rather than lowercasing repeatedly.
- `localDay()` returns a lowercase English day name: `"monday"`,
  `"tuesday"`, … `"sunday"`. Compare against lowercase literals.
- `hasVisitorTag(id)` takes the ID of a visitor-tag asset from the
  FunnelFlux UI. Only the user knows their own tag IDs. If the user hasn't
  supplied one, use a clearly-labelled placeholder (for example
  `"REPLACE_WITH_TAG_ID"`) and tell them to swap in the real ID from the
  interface.
- The time helpers (`timeInRange`, `timeAtOrAfter`, `timeAtOrBefore`,
  `localDay`) take an integer UTC hour offset — pass the `utcOffsetHours`
  variable (or a literal like `-7`, `0`, `3`). Never pass the `timezone`
  display string (`GMT+7`) to them.
- `timeInRange(start, end, offset)` uses HHMM integer times and supports
  overnight wraparound: when `end` is earlier than `start`, the range
  crosses midnight. For example, `timeInRange(2200, 600, utcOffsetHours)`
  matches 22:00 through 06:00 in the visitor's local time. No two-check
  workaround is needed.
- `trackingField(name)` reads URL key/value parameters that are defined in
  the traffic source config.
- `dataBuffer(name)` reads from the data buffer, which captures all URL
  key/value pairs across incoming redirect links, action links, and POST
  submissions — including values not defined in the traffic source. Use it
  for data submitted *after* the initial click, such as action-link params
  and form fields.
- `trackingField()` and `dataBuffer()` names must match
  `[A-Za-z0-9_ -]{1,64}`.
- Always call helpers with parentheses and a string argument:
  use `trackingField("utm_source")`, never `trackingFields["utm_source"]`.

## Allowed operators

`==`  `!=`  `<`  `>`  `<=`  `>=`  `&&`  `||`  `!`

## Allowed syntax

- `if` / `else`
- `switch`
- Local variables (`x := ...`)
- Local non-recursive functions or closures, with these constraints:
  - arguments must be typed `bool`, `int`, or `string`
  - must return exactly one `bool`, `int`, or `string` value
  - must return on every path
- Local `[]string` literals for helper inputs
- Comments with `//` or `/* */`

## Do not use

- Imports or package declarations
- Loops (`for`)
- Goroutines, `defer`, or `select`
- `append`, `make`, `new`, `panic`, `print`, `println`, `recover`,
  `delete`, or `copy`
- Maps or indexing of any kind, including `trackingFields["x"]`
- Pointers
- Unsupported packages
- Arbitrary method calls

## Good style

- Keep routing deterministic.
- Normalise an input once when you compare it repeatedly.
- Return early when a rule clearly matches.
- Use `switch` for several mutually exclusive cases.
- Use `default` only as the failure/error fallback; give "no rule matched"
  its own named route.
- Keep comments short and tied to the route they explain.

## Example: country routing

    if country == "US" {
        return "us"
    }

    if oneOf(country, "CA", "AU", "NZ") {
        return "tier_one"
    }

    return "default"

## Example: referrer block, then country tiers

    // Normalise the referrer once for case-insensitive matching.
    ref := strings.ToLower(referrer)

    // blocked: no referrer, or an unwanted / self-referral source.
    if ref == "" || strings.Contains(ref, "domain.com") {
        return "blocked"
    }

    // tier1: top-priority markets.
    if oneOf(country, "US", "CA", "GB", "AU", "NZ") {
        return "tier1"
    }

    // tier2: secondary markets.
    if oneOf(country, "DE", "FR", "NL", "SE", "NO", "DK", "CH", "IE") {
        return "tier2"
    }

    // unmatched: country resolved but matched no tier (a normal outcome).
    // A blank country (IP lookup failed) falls through to default instead.
    if country != "" {
        return "unmatched"
    }

    return "default"

## Example: case-insensitive tracking-field routing

    source := strings.ToLower(trackingField("utm_source"))

    switch {
    case source == "":
        return "missing_source"
    case source == "google_ads":
        return "google_ads"
    case strings.Contains(source, "newsletter"):
        return "newsletter"
    }

    return "default"

## Example: ISP substring blocklist

    normalizedISP := strings.ToLower(isp)
    blockedWords := []string{"amazon", "facebook", "google"}

    if containsAny(normalizedISP, blockedWords...) {
        return "blocked_isp"
    }

    return "default"

## Example: business-hours routing (visitor-local)

    // Uses the visitor's own offset, not a hardcoded one.
    workDay := oneOf(localDay(utcOffsetHours),
        "monday", "tuesday", "wednesday", "thursday", "friday")

    if workDay && timeInRange(900, 1700, utcOffsetHours) {
        return "business_hours"
    }

    return "default"

## Example: overnight local-time routing

    // end earlier than start crosses midnight: 22:00–06:00 local.
    if timeInRange(2200, 600, utcOffsetHours) {
        return "overnight"
    }

    return "default"

## Example: local closure

    isMobile := func() bool {
        return deviceType == "mobile"
    }

    isBusinessHour := func(offset int) bool {
        return timeInRange(900, 1700, offset)
    }

    if isMobile() && isBusinessHour(utcOffsetHours) {
        return "mobile_business_hours"
    }

    return "default"

## Example: submitted-form routing

    answer := strings.ToLower(dataBuffer("question_1"))
    consent := strings.ToLower(dataBuffer("consent"))

    if oneOf(answer, "a", "b") {
        return "answer_ab"
    }

    if oneOf(consent, "true", "yes", "1") {
        return "consented"
    }

    return "default"