Campaign Settings Technical Guide¶

This guide complements the UI workflow in docs/guides/campaign-page-navigation-guide.md. It describes the underlying setting schema returned by Lucit for a campaign, with emphasis on the data an LLM or AI assistant must understand when reading or reasoning about a campaign's configuration.

This is a reference for interpretation, not a save/update procedure. It explains:

the overall structure of the settings payload
the purpose of each setting group
what each key means and what type of value it expects
which settings are dependent on one another
where to look for deeper schema details, especially filters and slot behavior

1. Shape of the data¶

Campaign settings are stored under the top-level export_settings object. Each category contains an array of setting definitions. A setting is not just a value; it is a metadata object that tells the UI what it is and how it should behave. The format of each setting follows Lucit Form Fields Spec

{
  "success": true,
  "export_settings": {
    "loader": [
      {
        "key": "account_ids",
        "name": "Accounts",
        "type": "array",
        "required": true,
        "enum": true,
        "enum_multiple": true,
        "default_value": [{ "value": 101, "label": "Example Account" }],
        "value": [{ "value": 101, "label": "Example Account" }]
      }
    ],
    "general": [],
    "transformer": [],
    "puller": []
  }
}

Common fields on each setting object¶

Each setting usually includes the following:

key: stable internal identifier used by code and the UI
name: human-readable label shown in the settings dialog
type: primitive type such as bool, int, array, text, datetime
description: plain-language explanation of behavior
required: whether the setting is required in practice
default_value: baseline value used when unset
value: current effective value for the campaign
grid_size: layout width for the settings form
component: optional custom UI control, such as ItemFilter or AccountUserRoles
enum: if true, the field uses a fixed option list
enum_options: the allowed option list
depends_on: conditional visibility or enablement rules

Important interpretation rule¶

The AI assistant should treat default_value and value as the canonical baseline and current state, respectively. A setting may be present even when its effective value is null, empty array, or false.

2. Setting groups¶

The settings are organized into four main groups:

Group	Purpose
`loader`	Which inventory items are loaded into the campaign and from which accounts
`general`	Core operational settings, analytics, and reporting behavior
`transformer`	Creative generation, delivery fallback, and default creative logic
`puller`	How the campaign behaves when delivering content to a player or scheduler

`loader`¶

The loader group controls what gets pulled into a campaign before creative selection happens.

Typical keys:

loader_filter: filter expression used to decide which inventory items are allowed into the campaign
auto_add_new_items_to_export: if enabled, new matching items are automatically added
include_child_accounts: if enabled, include descendants of selected accounts
account_ids: collection of accounts to source inventory from

This category is used to enable the campaign to Automatically select the items that will run in the campaign based on the criteria that you specify. This can be useful for campaigns that pull creatives from multiple accounts, or campaigns that pull creatives based on conditions such as geo data (item locations based on geo polygons or radiuses) or other conditions like item tags, classes, titles etc.

Example use cases might be : - Only show real estate ads for houses within a 10 mile radius of some fixed point - Only show items tagged with "Christmas" - etc.

When these settings are NOT set (or left at their defaults) - Then, a user can manuall add/remove items from their campaign without these restrictions. This is the default behavior of most campaigns.

`general`¶

The general group defines operational behavior and campaign-level reporting rules.

Typical keys:

analytics_notifications: sends periodic analytics emails/notifications
analytics_notifications_user_roles: which roles receive analytics notifications
analytics_notifications_sold: notifies on removed/sold inventory items
analytics_notifications_sold_user_roles: roles that receive sold-item notifications
estimate_play_stats_from_daily_average_plays: use estimate-based analytics for legacy systems
estimated_total_plays_per_day: daily estimate for those calculations
estimated_plays_start_date_time / estimated_plays_stop_date_time: optional estimate windows
minimum_campaign_stopped_seconds_to_be_stopped: stop threshold for inactivity detection
verbose_logging: writes additional logs and converter caches
break_all_export_builds_up_by_board: break export work into board-sized jobs
break_all_export_builds_up_by_board_batch_size: size of those batches
plays_are_not_billable: campaign-level billing override for non-billable plays

Estimated Play Stats See Estimated Play Stats

Inactivity Detection Campaigns are moved into stats like Running, Paused, etc. The timeouts for these are based on this setting - minimum_campaign_stopped_seconds_to_be_stopped If a campaign is SUPPOSED to stop and start at various times through the day, increasing this number will stop that oscillation of states.

Break Up Buids Use these settings to improve performance and reduce timeouts for campaigns with large numbers of screens. Most programmatic campaigns have this enabled by default. It is also recommended for video campaigns (Campaigns that generate dynamic video)

`transformer`¶

The transformer group controls how creatives are generated, assigned, and delivered when no valid creative exists.

Typical keys:

attempt_to_auto_attach_missing_board_ids: auto-attach screens that request this campaign but are not attached
auto_generate_fallback_creatives: deliver fallback creative when nothing else matches
supports_puller_filtering: enable filter-aware requests from the player
puller_filtering_allowed_fields: allowed fields for player-side filtering
add_export_id_to_hash: include the export ID in generated creative hash identities
generate_video: generate video output for supported creatives
duration_seconds, fps, slow_zoom, zoom_percent: video generation parameters
default_creative_item_id: fallback creative when no eligible creative exists
disable_object_moderation_and_approve_all_creatives: broad override to bypass moderation checks

Puller Filtering See Configuring Dynamic Puller Filtering for infformation on puller filtering use cases and settings.

`puller`¶

The puller group controls request-level behavior between the player and campaign content delivery.

Typical keys:

enable_slot_dependency: turns on slot-aware selection logic
assume_no_slot_is_slot_one: if true, missing slot numbers default to slot 1
slot_dependency_settings: slot-aware repeat / no-repeat / advance rules
html_source: how HTML is delivered to the player (snapshot, drive_template, or on_demand)

This category is especially relevant for external player loops and multi-slot scheduling.

Slot Dependency See Configuring Slot Dependency

HTML Source By default this is set to snapshot for player systems that expect JPG assets returned to them.

For player systems that use a chromium based player, the recommended settings are drive_template or on_demand

To improve performance, Use on_demand for programmatic campaigns with constantaly updating data (e.g. weather temp, etc.)

3. Representative concrete example¶

To keep the data manageable for an LLM, the following condensed example shows the actual structure without every real-world account value.

{
  "success": true,
  "export_settings": {
    "loader": [
      {
        "key": "loader_filter",
        "name": "Item Filter",
        "type": "array",
        "description": "Filter the items that are fetched before they are added to the campaign",
        "component": "ItemFilter",
        "value": {
          "filter_fields": [
            {
              "field_name": "__logical_group",
              "operator": "and",
              "value": [
                {
                  "type": "filter_field",
                  "field_name": "inventory_item.category",
                  "operator": "equals",
                  "value": "automotive",
                  "objectClass": "App\\InventoryItem"
                }
              ],
              "isDirty": true,
              "isGroup": true
            }
          ],
          "filter_functions": []
        }
      },
      {
        "key": "auto_add_new_items_to_export",
        "name": "Auto Add New Items to Campaign",
        "type": "bool",
        "value": true
      },
      {
        "key": "include_child_accounts",
        "name": "Include Child Accounts",
        "type": "bool",
        "value": false
      },
      {
        "key": "account_ids",
        "name": "Accounts",
        "type": "array",
        "enum": true,
        "enum_multiple": true,
        "default_value": [{ "value": 101, "label": "Northwind Auto" }],
        "value": [{ "value": 101, "label": "Northwind Auto" }]
      }
    ],
    "general": [
      {
        "key": "analytics_notifications",
        "name": "Analytics Notifications",
        "type": "bool",
        "value": true
      },
      {
        "key": "estimated_total_plays_per_day",
        "name": "Estimated Total Plays Per Day",
        "type": "int",
        "value": 1350
      },
      {
        "key": "estimated_plays_start_date_time",
        "name": "Estimated Plays Start Date/Time",
        "type": "datetime",
        "value": null
      }
    ],
    "transformer": [
      {
        "key": "auto_generate_fallback_creatives",
        "name": "Deliver default creative if no creatives are eligible",
        "type": "bool",
        "value": true
      },
      {
        "key": "default_creative_item_id",
        "name": "Default Creative Item",
        "type": "int",
        "enum": true,
        "value": null
      },
      {
        "key": "generate_video",
        "name": "Generate Video",
        "type": "bool",
        "value": true
      }
    ],
    "puller": [
      {
        "key": "enable_slot_dependency",
        "name": "Enable Slot Dependency",
        "type": "bool",
        "value": false
      },
      {
        "key": "html_source",
        "name": "HTML Source Type",
        "type": "text",
        "enum": true,
        "value": "snapshot"
      }
    ]
  }
}

This is intentionally fictionalized and shortened. It preserves the structure, types, and semantics of the real settings without using production account identifiers or full enum lists.

4. Key semantics and behaviors¶

4.1 `loader_filter` and item selection¶

loader_filter is a filter object built using the Lucit filter-builder format. It is used to restrict which inventory items are pulled into the campaign before creative assignment happens.

The important rule for an AI assistant is:

it is not a generic free-form string
it is structured filter JSON using filter_fields and filter_functions
it supports logical groups using the special field name __logical_group
groups use operator values like and and or
nested groups are allowed, but each branch must be marked correctly as a group (isGroup: true)

For the exact filter-tree contract, see docs/developer/macros/filter-builder-reference.md.

The loader_filter is used when the UI says:

"Auto Add New Items to Campaign"
"Item Filter"
the campaign imports or updates its inventory dynamically

This setting is extremely important because it affects the campaign input set, not just display.

4.2 `account_ids`¶

account_ids is an array of account identifiers used as sourcing accounts for campaign inventory.

It often appears with:

enum: true
enum_multiple: true
default_value as an array of { "value": <id>, "label": <name> }
value as the current selected accounts

This field should be interpreted as a selection list, not a username or account slug. The actual programmatic value is the numeric identifier; the label is the display name.

4.3 Analytics and notification settings¶

Campaign-level notifications are grouped behaviorally:

analytics_notifications => campaign performance notifications
analytics_notifications_user_roles => who receives them
analytics_notifications_sold => removal/sold-item escalation
analytics_notifications_sold_user_roles => who receives sold-item alerts

These settings are operational and often user-role sensitive. The value arrays for roles are often enumerated with values like account_admin, user, or account_exec.

4.4 Estimated play analytics¶

Settings like:

estimate_play_stats_from_daily_average_plays
estimated_total_plays_per_day
estimated_plays_start_date_time
estimated_plays_stop_date_time

are used for systems that do not provide full playback reporting. In those cases, Lucit estimates play counts based on configured daily averages and timing windows.

These settings are especially relevant for older or legacy player integrations, and they should be considered campaign forecasting controls rather than actual proof-of-play data.

4.5 Fallback and default creative behavior¶

The transformer settings define what happens when a campaign cannot match a screen or item to a valid creative.

Most important ones:

auto_generate_fallback_creatives controls whether a default creative is generated automatically
default_creative_item_id chooses the fallback creative to use
attempt_to_auto_attach_missing_board_ids allows screens not attached to the campaign to self-attach when they request it

This is intentionally delivery-risk logic: it affects what the player receives if there is no valid campaign match.

4.6 Video generation settings¶

When generate_video is enabled:

duration_seconds sets the video length
fps sets frame rate
slow_zoom controls whether a slow zoom is used
zoom_percent sets the amount of zoom

These settings are interdependent: they are meaningful only when the video generation workflow is active.

4.7 Slot dependency and `html_source`¶

The puller settings determine how campaign content is delivered to a player.

enable_slot_dependency turns on loop-aware slot behavior
slot_dependency_settings stores the per-slot dependency rules that define one slot as normal / advance / repeat / no-repeat relative to another slot
assume_no_slot_is_slot_one treats missing slot numbers as slot 1 when necessary
html_source controls how the campaign HTML is delivered (snapshot, drive_template, or on_demand)

This category is more advanced and is mostly relevant for multi-slot or external-player scheduling workflows. For deeper semantics, see docs/guides/how-tos/configuring-campaign-slot-dependency-settings.md.

5. Dependency and conditional logic¶

Many settings are not independent. The JSON often uses depends_on to hide or enable fields based on other keys.

Examples:

puller_filtering_allowed_fields depends on supports_puller_filtering
duration_seconds, fps, slow_zoom, and zoom_percent depend on generate_video
assume_no_slot_is_slot_one depends on enable_slot_dependency

This means an LLM should not assume that every setting is always relevant or active. A setting may exist in the schema but be logically irrelevant unless the parent condition is true.

6. Data types and value expectations¶

The settings use a small set of common primitive types.

`bool`¶

Boolean toggles are used for clear on/off choices. Example:

{
  "key": "auto_generate_fallback_creatives",
  "type": "bool",
  "value": true
}

`int`¶

Integer values are used for numeric thresholds and sizing values. Example:

{
  "key": "estimated_total_plays_per_day",
  "type": "int",
  "value": 1350
}

`array`¶

Arrays are used for multi-select values and list-like data. Example:

{
  "key": "analytics_notifications_user_roles",
  "type": "array",
  "value": ["account_admin", "user", "account_exec"]
}

`datetime`¶

Datetime fields are strings or null values that represent a date/time when a particular behavior starts or stops. They are not ordinary text fields and should be treated as timestamp-like values.

`text`¶

Text fields are used for string-based settings such as the HTML source mode.

7. Safe interpretation for an AI assistant¶

When reading campaign settings, an LLM should use these rules:

Treat the setting object as schema metadata plus the current value.
Use value to determine the effective state of a campaign.
Use default_value as the fallback baseline only when value is missing or empty.
Treat enum_options as UI labels, but use the underlying value in programmatic logic.
Follow depends_on before deciding whether a field is active or meaningful.
For filter logic, use the filter-builder contract rather than guessing based on labels.
For slot logic, understand it as a delivery strategy for multi-slot loops, not as a generic creative filter.

8. Summary of the most important settings¶

If you were building a quick mental model for a campaign, these are the highest-value settings to understand first:

account_ids: what accounts the campaign pulls from
loader_filter: what inventory items are allowed in
analytics_notifications*: reporting and alerting behavior
estimated_total_plays_per_day and related estimate fields: analytics forecasting
auto_generate_fallback_creatives and default_creative_item_id: what happens when no creative matches
generate_video + video parameters: how motion creatives are produced
enable_slot_dependency and html_source: delivery strategy for slot-aware or HTML-based players

These settings define the campaign's real operational envelope: what enters the campaign, how it is evaluated, how it is delivered, and what the user sees when a downstream system requests content.

9. Additional technical references¶

This document intentionally focuses on the structure and meaning of Lucit's campaign settings object so an AI assistant can reason about it without needing to know the exact UI save flow.

Campaign Settings Technical Guide¶

1. Shape of the data¶

Common fields on each setting object¶

Important interpretation rule¶

2. Setting groups¶

loader¶

general¶

transformer¶

puller¶

3. Representative concrete example¶

4. Key semantics and behaviors¶

4.1 loader_filter and item selection¶

4.2 account_ids¶

4.3 Analytics and notification settings¶

4.4 Estimated play analytics¶

4.5 Fallback and default creative behavior¶

4.6 Video generation settings¶

4.7 Slot dependency and html_source¶

5. Dependency and conditional logic¶

6. Data types and value expectations¶

bool¶

int¶

array¶

datetime¶

text¶

7. Safe interpretation for an AI assistant¶

8. Summary of the most important settings¶

9. Additional technical references¶

`loader`¶

`general`¶

`transformer`¶

`puller`¶

4.1 `loader_filter` and item selection¶

4.2 `account_ids`¶

4.7 Slot dependency and `html_source`¶

`bool`¶

`int`¶

`array`¶

`datetime`¶

`text`¶