Push Screen Data to Lucit for Creative Triggers

Use a local application or script to push changing data to individual screens in Lucit, then use that data in a creative's screen filter. Examples include store availability, traffic conditions, wait times, and local event status.

This guide uses a private application with the Data Application (Push) capability configured as a Key Value data source. The example pushes a traffic level to each screen so a creative can be eligible only where traffic is heavy.

Use Cases are for any type of data that you can tie to a screen or its geographic location. It could be 1st party private data, audience data, traffic data, etc. Anything in which you can resolve data points to key/value pairs to a specific screen location.

NOTE: Data created in this way can also be used on templates themselves. The data will appear as macros in the template designer.

1. Create and Configure Your Private App

1. Enable Developer Mode in your Lucit personal settings.
2. Create a private application and give it a descriptive name, such as Local Traffic Data.
3. Add the Data Application (Push) capability.
4. Click the gear/settings icon for that capability.
5. Configure the data source type. The available choices include Inventory Item and Key Value. Select Key Value for this guide and save your settings.
6. On the application's Tokens tab, generate a token and secret. Record the Application ID from the app's General tab.
7. Add your new app to the Lucit account that contains your campaign.

The account's data source is the connection your script will use to push values. Screen values written through this endpoint are scoped to the data source's account. They are not inherently limited to one campaign in that account, so choose descriptive keys and coordinate their use across campaigns.

2. Authenticate Your Local Script

The examples below use Bash, curl, and jq. Run them in the same shell session and replace placeholder values with your own. Supply credentials through your local environment or secret manager; do not commit them to source control.

export LUCIT_API_BASE='https://api.lucit.app/api/v3'
export LUCIT_APP_ID='LCUID-LAP-REPLACE_WITH_YOUR_APP_UUID'
export LUCIT_ACCOUNT_LCUID='LCUID-LA-REPLACE_WITH_YOUR_ACCOUNT_UUID'
export LUCIT_CAMPAIGN_LCUID='REPLACE_WITH_YOUR_CAMPAIGN_LCUID'

# Set LUCIT_LOGIN_TOKEN and LUCIT_LOGIN_SECRET securely before continuing.
: "${LUCIT_LOGIN_TOKEN:?Set your app login token}"
: "${LUCIT_LOGIN_SECRET:?Set your app login secret}"
set -o pipefail

LUCIT_BEARER_TOKEN=$(
  jq -n '{token: env.LUCIT_LOGIN_TOKEN, secret: env.LUCIT_LOGIN_SECRET}' |
    curl --fail-with-body --silent --show-error --max-time 30 \
      --request POST "$LUCIT_API_BASE/auth" \
      --header "AppIdV3: $LUCIT_APP_ID" \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --data-binary @- |
    jq -er 'select(.ok == true) | .token | strings | select(length > 0)'
) || { echo 'Authentication failed' >&2; exit 1; }
export LUCIT_BEARER_TOKEN

The returned bearer token is different from your app's login token. Reuse it for subsequent requests. Every request includes AppIdV3; authenticated requests also include Authorization: Bearer ....

3. Find the Account Data Source LCUID

Use either of these methods after adding the app to your account.

Option A: Developer Object Info Panel

1. Open the account and locate the data source created by your app.
2. Open that data source's Settings.
3. Open the Developer Object Info Panel.
4. Copy the data source's LCUID (LCUID-LF-...).

Option B: List the Account's Data Sources Through the API

curl --fail-with-body --silent --show-error --max-time 30 \
  "$LUCIT_API_BASE/accounts/$LUCIT_ACCOUNT_LCUID/data-sources" \
  --header "Authorization: Bearer $LUCIT_BEARER_TOKEN" \
  --header "AppIdV3: $LUCIT_APP_ID" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' |
  jq '.data_sources[] | {name, lcuid, provider: .data_source_provider.name}'

Illustrative output:

{
  "name": "Local Traffic Data",
  "lcuid": "LCUID-LF-11111111-1111-4111-8111-111111111111",
  "provider": "Local Traffic Data"
}

Find the entry associated with your app and copy its top-level lcuid. Use the data source LCUID, not the nested data_source_provider.lcuid (LCUID-LFP-...) or your application ID (LCUID-LAP-...).

export LUCIT_DATA_SOURCE_LCUID='LCUID-LF-REPLACE_WITH_YOUR_DATA_SOURCE_UUID'

This value fills the {dataSourceId} parameter in the key/value endpoints below.

4. Map Your Data to the Campaign's Screens

List the screens assigned to your campaign:

curl --fail-with-body --silent --show-error --max-time 30 \
  "$LUCIT_API_BASE/campaigns/$LUCIT_CAMPAIGN_LCUID/digital-boards?page=1&per_page=100" \
  --header "Authorization: Bearer $LUCIT_BEARER_TOKEN" \
  --header "AppIdV3: $LUCIT_APP_ID" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' |
  jq '{screens: [.digital_boards[] | {name, board_identifier, lcuid}], pagination}'

Fetch additional pages through pagination.last_page when needed. Map each external location or screen ID to the corresponding screen's lcuid (LCUID-LB-...). Keep that mapping in your application. Use the returned identifiers rather than matching screen names on every update.

export LUCIT_SCREEN_LCUID='LCUID-LB-REPLACE_WITH_YOUR_SCREEN_UUID'

5. Push a Value for a Screen

Create or update a key with:

PUT /api/v3/digital-boards/{screenLcuid}/key-value-store/{dataSourceId}/{key}

For example, set localtraffic_level to heavy:

curl --fail-with-body --silent --show-error --max-time 30 \
  --request PUT \
  "$LUCIT_API_BASE/digital-boards/$LUCIT_SCREEN_LCUID/key-value-store/$LUCIT_DATA_SOURCE_LCUID/localtraffic_level" \
  --header "Authorization: Bearer $LUCIT_BEARER_TOKEN" \
  --header "AppIdV3: $LUCIT_APP_ID" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"key_name":"Local Traffic: Level","value":"heavy"}'

Parameter	Purpose
screenLcuid	The Lucit screen receiving the value.
dataSourceId	The account data source LCUID from step 3.
key	A stable identifier for the data point, such as localtraffic_level.
key_name	An optional friendly label; Lucit derives one from the key if omitted.
value	The current value. The stored value must fit within 255 bytes. Non-string JSON values are stored as JSON text.

Use the same key on each screen, with the appropriate value for that screen. Sending another PUT for the same screen, data source, and key updates that value. Use simple, namespaced keys containing letters, numbers, and underscores.

For example, one screen might receive heavy, another light, and a third moderate. A single creative filter can then evaluate the appropriate value for each screen.

Read back the screen's values to verify the update:

curl --fail-with-body --silent --show-error --max-time 30 \
  "$LUCIT_API_BASE/digital-boards/$LUCIT_SCREEN_LCUID/key-value-stores/$LUCIT_DATA_SOURCE_LCUID" \
  --header "Authorization: Bearer $LUCIT_BEARER_TOKEN" \
  --header "AppIdV3: $LUCIT_APP_ID" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' |
  jq '.key_value_stores[] | {key_name, key, value, macro}'

The response includes a macro identifier, such as digital_board.store.localtraffic_level. Use the identifier returned by Lucit when referencing the field programmatically.

6. Use the Value in a Creative Trigger

1. Open the campaign and the creative you want to control.
2. Open its screen filtering controls.
3. Select the dynamic screen field corresponding to Local Traffic: Level.
4. Set the condition to equals heavy and save.

Lucit's filter builder includes dynamic key/value fields for screens in the account. With this condition, the creative is eligible only on screens whose traffic level is heavy, subject to its other targeting, scheduling, and approval requirements.

Change the value to light and verify that the creative no longer meets that condition on the selected screen. Configure a fallback creative for situations where the condition does not match or the data is unavailable.

If constructing filters through the API, use the actual field metadata and supported operators from Lucit's filter builder. Storing a number or boolean as JSON does not, by itself, establish the field's comparison type. Validate numeric and boolean conditions before relying on them.

7. Automate Ongoing Updates

Run your application as a scheduled task or a background service. On each update, collect the latest external data, resolve the screen LCUID, and PUT each changed value to Lucit. Keep the trigger configured in Lucit; your script updates the data it evaluates.

• Send changes efficiently. Avoid rewriting unchanged values unless you are deliberately updating freshness information. Keep requests bounded and respect API limits.
• Handle failures. Set request timeouts, check HTTP errors and the response's success field, and retry temporary failures with backoff. Log the screen, key, and result without logging credentials.
• Preserve update order. Serialize writes to the same screen/key so a delayed older request cannot overwrite newer data.
• Define stale-data behavior. Optionally publish an observation timestamp and implement a freshness rule or watchdog. A timestamp alone does not expire a value; account for the script itself stopping.
• Measure delivery timing. Test the delay between a successful write, filter reevaluation, and playback. Choose an update interval that fits the campaign and player integration; API acceptance does not guarantee immediate playback.

Start with one screen and one key. Verify both matching and nonmatching values, fallback behavior, and update timing before expanding to the full campaign.

API References

• Authentication
• List account data sources
• List campaign screens
• Create or update a screen key/value
• Read screen key/values
• Filter Builder Reference