Skip to content

How to Use Geo Tags with Ad Post Templates

Overview

This guide walks you through adding geographic location fields to your templates that allow users to attach geo tags to items during the manual Post Ad process. By adding a custom geo field using the GooglePlaceFinder component, you can capture location data (cities, addresses, regions, etc.) and then use that geographic information within your creative templates through custom designer functions.

What are Geo Tags?

Geo Tags are location objects that get attached to Items in Lucit to store geographic information. Once an item has a geo tag, it can be used in campaigns that target specific geographic areas, and the location data within the geo tag can be displayed in your creatives.

Custom Fields are fields that you add to templates to capture or display custom information. In this case, we'll create a custom field using the GooglePlaceFinder component, which will create geo tags when users post ads manually.

Post Ad verus just Editing Geo Tags

This guide is specifically about asking users to enter Geo Tags when Posting Ads from a template you have created.

If you goal is to simply edit the geo tags for any creative item, just use the "Geo Tags" section on the item's edit page.

Objective

By the end of this guide, you will have:

  • Created or opened a template for editing
  • Added a custom designer function that reads geo tag data
  • Created a custom field in your Field Map using the GooglePlaceFinder component
  • Connected the field to your template to display location values
  • Tested the geo field using the POST AD button

Prerequisites

Before starting this guide, ensure you have:

  • A Lucit account with appropriate permissions to create and edit templates
  • An existing campaign with at least one screen attached
  • Permission to access the Template Designer

Example Scenario

Throughout this guide, we'll create a template field that captures an honoree's hometown during ad posting. The template will then display the city name from that geo tag in the creative.

Understanding the Workflow

Here's how geo tags work with templates:

  1. Define a designer function that can read and parse geo tag data
  2. Add a field to the Field Map that uses the GooglePlaceFinder component
  3. Connect the field in your Field Code to display the extracted value
  4. During POST AD, users select a location from an autocomplete dropdown
  5. The geo tag is saved to the item's inventory attributes
  6. The template displays the extracted value (e.g., city name) in the creative

Step 1: Create or Open a Template

Create a New Template

If you're starting from scratch:

  1. Navigate to Templates -> CREATE A NEW TEMPLATE
  2. Choose "Data Connected Template"
  3. Select your Screen Formats
  4. Click `NEXT'
  5. Click New : Create a new template from scratch on a blank canvas

Open an Existing Template

If you're editing an existing template:

  1. Navigate to Templates
  2. Find the template you want to edit
  3. Click on the template name or the edit icon to open the Template Designer

Note: You should now be in the Template Designer interface where you can edit code, field maps, and design elements.

Step 2: Add a Designer Function to Read Geo Tags

Designer functions are custom JavaScript functions that process data within your templates. To use any values from a geo tag, you must register a custom designer function. Learn More about Designer Functions

  1. In the Template Designer, in the Actions Bar at the botton of the canvas, click the <> icon to open the Code Editor` dialog
  2. Click on the JS (JavaScript) tab within the Code Editor

Add the Geo Tag Parser Function

Copy and paste the following code into the JS editor:

registerDesignerFunction("fnGetCityNameFromGeoTag", (params) => {
  const serializedGeoTag = params[0] ?? null;

  if (!serializedGeoTag) 
  {
     console.log("Geo Tag is Empty");
     return "";
  }

  try {
    const geoTag = JSON.parse(serializedGeoTag);

    if (!geoTag) 
    {
      console.log("Could not parse Geo Tag");
      return "";
    }

    const cityName = geoTag?.place?.city;

    if( !cityName) 
    {
       console.log("Empty City Name");
       return "";
    }

    return cityName;
  } catch (e) {
    console.log(e);
     return "";
  }
});

Understanding This Function

  • Function Name: fnGetCityNameFromGeoTag - You can name this anything descriptive
  • Parameter: params[0] receives the serialized geo tag string from the item's inventory attributes
  • It's wrapped in an array: The function expects parameters as an array, which is why we pass ['{{item.inventory_attributes.hometown}}'] later
  • Parsing: The function converts the JSON string into a JavaScript object
  • Extraction: It reads the city property from geoTag.place.city
  • Error Handling: Returns an empty string if any step fails, preventing template errors
  • Console Logging: Helps with debugging if the geo tag isn't working as expected

Important: Click SAVE or the save button to preserve your changes.

Step 3: Create a Custom Field in the Field Map

Now we'll create the field that users will interact with during the POST AD process.

Add a new Custom Field

  1. In the Template Designer, on the Elements Panel under Dyamic Data Elements find Custom Field and click on the + icon.
  2. Give the field a name
  3. Click on the FIELD MAP tap to add a field map.

Add the GooglePlaceFinder Field

Add the following JSON to your Field Map array.

[
  {
    "key": "hometown",
    "name": "Honoree Hometown",
    "type": "string",
    "component": "GooglePlaceFinder",
    "component_options": {
      "show_confirm_checkbox": false,
      "types": [
        "(cities)"
      ]
    }
  }
]

Understanding the Field Configuration

  • key: "hometown" - The unique identifier for this field. This must match what you reference in Field Code as item.inventory_attributes.hometown
  • name: "Honoree Hometown" - The label shown to users during POST AD
  • type: "string" - The data type stored
  • component: "GooglePlaceFinder" - Uses Google Places API to provide location autocomplete
  • component_options:
    • show_confirm_checkbox: false - Hides the confirmation checkbox that normally appears when a valid location is selected
    • types: ["(cities)"] - Restricts the autocomplete to only show cities

Google Places Types Reference

You can customize what types of locations appear in the autocomplete by changing the types array. Here are common options:

Geographic Types:

  • "(cities)" - Cities only
  • "(regions)" - Administrative regions (states, provinces, etc.)
  • "geocode" - All geographic results
  • "address" - Street addresses
  • "establishment" - Businesses and points of interest

Multiple Types:

Currently, we support using only a single one of the above types. So you can do ["establishment"] but NOT ["establishment","(cities)"]

For complete type options, refer to the Google Places API Type Documentation.

Step 4: Add the Field Code to Display the Value

  1. In The Custom Field editor for this field
  2. Click on the FIELD CODE tab

Add the Function Call

In the Field Code editor, add the following code:

fnGetCityNameFromGeoTag(['{{item.inventory_attributes.hometown}}'])

Understanding This Code

  • Function name: fnGetCityNameFromGeoTag matches the designer function we created in Step 2
  • Parameter array: We pass an array with a single element: '{{item.inventory_attributes.hometown}}'
  • Template variable: {{item.inventory_attributes.hometown}} will be replaced with the actual geo tag data when the template renders
  • Attribute name match: hometown matches the key we defined in the Field Map in Step 3

Where Will This Value Appear?

The value returned by this function (the city name) will appear wherever you place this Custom Field in your template design. You can:

  • Position it like any other field on your canvas
  • Style it with fonts, colors, and sizes
  • Combine it with other text or fields
  • Use it in animations

Important: Click SAVE to preserve your Field Code changes.

Step 5: Position the Field in Your Design

Add the Field to Your Canvas

  1. In the Template Designer's canvas/design area, locate the Custom Field you just created
  2. Drag it to where you want the city name to appear in your creative
  3. Resize and style it as needed using the design tools
  4. You can change fonts, colors, alignment, and other visual properties

Tip: During design, the field might show placeholder text or be empty. It will populate with actual city names during the POST AD process.

Step 6: Test with POST AD

Now let's test the geo tag field to ensure it works correctly.

Access the POST AD Function

  1. While in the Template Designer, locate the POST AD button (typically in the upper right area)
  2. Click POST AD to begin the manual ad posting workflow

What to Expect

When you click POST AD, you will see:

  1. A form appears with all the fields defined in your Field Map
  2. The "Honoree Hometown" field (or whatever you named it) will display
  3. An autocomplete input box that you can type into
  4. As you type, Google Places will suggest matching cities
  5. Location suggestions appear in a dropdown list below the input
  6. Each suggestion shows the full place name (e.g., "Chicago, IL, USA")
  7. Click a suggestion to select it
  8. The field populates with your selection
  9. No confirmation checkbox appears (because we set show_confirm_checkbox: false)

Complete the POST AD Process

  1. Fill in any other required fields in the form
  2. Select the campaign and screens where you want to post this ad
  3. Click the final POST AD or SUBMIT button
  4. The ad will be created with the geo tag attached to the item

Verify the Result

After posting:

  1. Navigate to your campaign to see the newly posted creative
  2. The creative should display the city name you selected (e.g., "Chicago")
  3. If you edit the item later, you can navigate to the Item Edit Page to see the full geo tag data

Adding Multiple Geo Fields

You can add multiple geographic fields to the same template. To do this, create new custom fields for each one and use a DIFFERENT field map key / attribute. You can re-use the fnGetCityFromHometown designer function

Accessing Other Geo Tag Properties

The geo tag object contains more than just the city name. You can extract other properties by modifying your designer function.

Available Geo Tag Properties

Common properties available in the geoTag.place object include:

  • geoTag.place.city - City name (New York)
  • geoTag.place.state - 2 Letter State/province name (NY)
  • geoTag.place.country - 2 Letter Country name (US)
  • geoTag.place.name - Place name (for establishments), or City, State
  • geoTag.location - Latitude
  • geoTag.location - Longitude

Note - See Google Documentation for a complete reference to available place properties when using different component_options.types

Example: Getting State Name

registerDesignerFunction("fnGetStateFromGeoTag", (params) => {
  const serializedGeoTag = params[0] ?? null;
  if (!serializedGeoTag) return "";

  try {
    const geoTag = JSON.parse(serializedGeoTag);
    return geoTag?.place?.state ?? "";
  } catch (e) {
    return "";
  }
});

Example: Getting Full Address

registerDesignerFunction("fnGetFullAddress", (params) => {
  const serializedGeoTag = params[0] ?? null;
  if (!serializedGeoTag) return "";

  try {
    const geoTag = JSON.parse(serializedGeoTag);
    return geoTag?.place?.formatted_address ?? "";
  } catch (e) {
    return "";
  }
});

Example: Combining Multiple Properties

registerDesignerFunction("fnGetCityState", (params) => {
  const serializedGeoTag = params[0] ?? null;
  if (!serializedGeoTag) return "";

  try {
    const geoTag = JSON.parse(serializedGeoTag);
    const city = geoTag?.place?.city ?? "";
    const state = geoTag?.place?.state_short ?? "";

    if (city && state) {
      return `${city}, ${state}`;
    } else if (city) {
      return city;
    } else if (state) {
      return state;
    }
    return "";
  } catch (e) {
    return "";
  }
});

Tips & Best Practices

Field Naming

  • Use descriptive, unique key values in your Field Map that clearly indicate the purpose (e.g., hometown, event_location, business_address)
  • Keep keys lowercase and use underscores for multi-word names
  • The name property should be user-friendly as it appears in the POST AD form

Designer Function Best Practices

  • Always include error handling (try/catch blocks)
  • Return empty strings rather than null or undefined to prevent template rendering errors
  • Use optional chaining (?.) to safely access nested properties
  • Add console.log statements for debugging during development
  • Name functions descriptively based on what they extract (e.g., fnGetCityName, fnGetStateCode)

Google Places Configuration

  • Choose the most specific types that match your use case to reduce irrelevant suggestions
  • Consider setting show_confirm_checkbox: true if you want users to verify their selection
  • Test different type combinations to find what works best for your workflow

Testing

  • Always test with POST AD before deploying templates to production
  • Try edge cases like:
    • Not selecting a location (field left empty)
    • Selecting different types of places
    • Multiple geo fields in the same template
  • Check the browser console for any error messages from your designer functions

Using Geo Tags in Campaigns

  • Remember that items created with geo tags can be filtered in campaigns by geographic area
  • You can create campaigns that automatically pull in all items from specific cities or regions
  • Geo tags provide more than just display values—they enable location-based campaign automation
  • Note: Geographic Campaign settings are set in the campaign filter in the Campaign Settings Dialog (See Campaign Page Navigation Guide

Troubleshooting

Issue: Geo Field Not Appearing During POST AD

Possible Causes:

  • Field Map JSON is malformed or has syntax errors
  • The Field Map hasn't been saved
  • The template hasn't been fully saved after adding the field

Solution:

  • Check the Field Map for JSON syntax errors (missing commas, brackets, quotes)
  • Ensure you clicked SAVE after editing the Field Map
  • Refresh the Template Designer and try POST AD again

Issue: City Name Not Displaying in Creative

Possible Causes:

  • Designer function has an error or wasn't registered
  • Field Code references the wrong attribute key
  • The Custom Field isn't positioned on the canvas

Solution:

  • Verify the designer function name matches exactly in Field Code
  • Check that item.inventory_attributes.{key} matches your Field Map key
  • Open browser console to check for JavaScript errors
  • Ensure the Custom Field is visible and positioned on your template canvas

Issue: Autocomplete Dropdown Not Working

Possible Causes:

  • Google Places API issues (rare)
  • Internet connectivity problems
  • Component configuration error

Solution:

  • Check your internet connection
  • Verify "component": "GooglePlaceFinder" is spelled correctly
  • Try refreshing the Template Designer
  • Check the browser console for API errors

Issue: Wrong Type of Locations Appearing

Possible Causes:

  • The types array in component_options contains incorrect or too broad types

Solution:

Issue: Function Returns Empty String

Possible Causes:

  • The geo tag structure doesn't contain the property you're trying to access
  • The user didn't select a location during POST AD
  • The property path in your function is incorrect

Solution:

  • Check browser console logs from your function
  • Add more detailed logging to inspect the actual geo tag structure: 
    console.log("Full Geo Tag:", geoTag);
console.log("Place object:", geoTag?.place);
  • Verify the property exists in the geo tag for the type of location you selected
  • Make sure users actually select a location during POST AD

What Happens After

After completing this guide:

  • Your template will have a geographic field that users can interact with during manual POST AD
  • Every item created from this template will have geo tag data stored in its inventory attributes
  • The geo tag values you extract will display in your creatives wherever you positioned the Custom Field
  • You can use these geo-tagged items in geographically targeted campaigns
  • Users can manually add or edit geo tags on items from the Item Edit Page at any time

Common Questions

Can I edit the geo tag after posting the ad?

Yes. Navigate to the Item Edit Page for any item, and you can manually add or modify geo tags from there.

Can I use geo tags in campaigns to target specific areas?

Yes. You can create campaigns that automatically bring in all items from a specific geographic area based on their geo tags.

Do I need a Google API key?

No. The GooglePlaceFinder component uses Lucit's Google Places integration, so you don't need to provide your own API key.

Can I require the geo field to be filled out?

Yes. You can add validation rules to your Field Map configuration to make fields required. Add "required": true to the field definition. And be sure that the Element is not set to "Optional" in the Element's settings. After adding the field, Right Click on the Element on the Canvas and choose "Edit Settings"

What if I want to capture something other than cities?

Change the types array in component_options to match your needs. For example, use ["establishment"] for businesses or ["address"] for street addresses.

Can I use multiple geo fields with the same types?

Yes. As long as each field has a unique key, you can have multiple fields with the same types configuration.

How do I display both city and state?

Create a designer function that combines multiple properties (see the "Combining Multiple Properties" example in the "Accessing Other Geo Tag Properties" section above).