Skip to main content

Audience & Segment Schema

Overview​

Audience segments in GoWit’s retail media platform are partner-defined user groups such as “VIP Members” or “Loyalty Tier 3”. These segments control which campaigns can show ads to which users, but GoWit does not create or manage them.

Instead, the marketplace partner defines the segments and assigns users to them. GoWit simply receives the segment IDs in real time and uses those IDs to determine campaign eligibility.

In short: you own the segment definitions and membership; GoWit only uses the IDs you send to decide which campaigns can serve ads to each user.

What is a Segment in GoWit’s Ad Platform

In GoWit, a segment is a partner-defined audience group—such as “VIP Members” or “Loyalty Tier 3”—based on behavior, demographics, or any custom criteria you define in your own systems (like a CRM or CDP).

Each segment is identified by a unique Segment ID and a descriptive name. These belong to your marketplace only; they are not shared across different retailers.

Key Points​

  • Externally Defined: Segments and their membership are created and managed entirely by the partner. GoWit does not generate or assign segment logic—it simply uses what you provide.
  • Identification: You supply a Segment ID and name; GoWit stores these and maps them internally. Developers treat the Segment ID as the main reference.
  • No Logic Stored: GoWit doesn’t store the rules behind the segment (for example, “Premium Customers = spent > $1000”). It only needs to know which users belong to that segment via the Segment ID in each ad request.

In short: you own the audience definitions; GoWit simply consumes the Segment IDs you send in real time to decide which campaigns can show ads to each user.

Required Fields​

To integrate segment data, you need to provide a minimal set of identifiers that tie users to segments.

The data schema for audience segment integration is straightforward:

FieldDescription
external_segment_idUnique ID you assign (e.g. "SEG-423"). Sent in each user’s segment_ids list so GoWit can match campaigns to that audience.
nameHuman-readable label (e.g. "Premium Customers") shown in the campaign UI so advertisers can select the segment.

Syncing Segments: How It Works​

Custom segments created in the marketplace must be shared with GoWit via API-based sync.
There is no UI or manual upload option — syncing is entirely programmatic and should be integrated into your system workflows.

Lifecycle​

  1. Define a segment in your system
    Categorize a group of users based on behavior (e.g., “Viewed product X but didn’t purchase”).

  2. Sync that segment with GoWit
    Use the API to let the platform know this audience exists, giving it an ID and a name.

    • Once synced, this segment becomes selectable in campaign targeting.

  3. Qualify users in real-time
    When an ad request or user interaction happens, your system must indicate which segments the user belongs to.

    • GoWit uses this data to match the user to campaigns targeting those audiences.

  4. Campaigns target synced segments
    Advertisers can configure campaigns to deliver only to users in specific segments you’ve synced (e.g., “Loyal Buyers” or “Pet Category Viewers”).

Keeping Segments Up to Date​

Segments naturally evolve as business strategies change. To maintain clean targeting and avoid clutter:

  • Rename segments when audience labels change (e.g., “High Value Users” → “VIP Customers”).
  • Split or merge segments to refine targeting (e.g., replace “All Purchasers” with separate category-level segments).
  • Remove inactive segments when they are no longer relevant.

Benefits of Keeping Segment List Current​

  • Advertisers see only meaningful options in the campaign targeting UI.
  • Campaigns don’t reference outdated or unused segments.
  • No “orphaned” segments remain in the system that could cause confusion or mis-targeting.

Campaign Targeting with Segments​

Once segments are integrated and users’ segment IDs are being sent in requests, how does this affect campaign selection?

GoWit’s campaign configuration allows advertisers (or the retailer) to specify audience segment targeting as part of a campaign’s settings.

How It Works​

  • Declaring Target Segments

    • When creating or editing a campaign, you can specify one or multiple segment IDs that the campaign should target.
    • Stored as a list of segment IDs in the campaign data model.
    • Example: A campaign could target segment ID 101 (or multiple segments like 101 and 102).
    • In the UI or API, this might be called “Audience Targeting.”
    • If a campaign has no segments listed → it’s open to all users (segment-unrestricted).
    • If it has specific segments → only users in those segments should see the ads.
    • Schema includes an all_segments flag:
      • By default, a new campaign targets all segments unless you restrict it.

  • Multiple Segments Logic

    • If multiple segment IDs are attached, the logic is inclusive (OR).
    • A campaign will serve to any user who is in at least one targeted segment.
    • Example: Campaign targets {A, B, C} →
      • User in A qualifies
      • User in B qualifies
      • User in A & C qualifies (no extra weight for multiple matches).
    • Key rule: As long as there’s intersection between user’s segments and campaign’s segments, the campaign is eligible.

  • Ad Request Filtering
    During an ad request, the platform evaluates all active campaigns and filters out those that don’t match the user’s segment profile.

    System checks:

    • Campaign has no segment targeting → not filtered out (eligible).
    • Campaign has segment targets but no match → excluded from auction.
    • At least one match → remains eligible.

    Example:

    • Campaign 17 targets [“VIP_USERS”].
    • User request has segment_ids: ["ABANDONED_CART"] → campaign skipped.
    • User request has segment_ids: ["VIP_USERS"] → campaign included.

    GoWit’s event logs record which segment IDs were present in requests for debugging and analytics.

    Decision-making is real-time and based solely on segment IDs.

  • Combining with Other Targeting

    • Segments are just one layer of targeting.
    • Campaigns can also target keywords, categories, locations, devices, ages, etc.
    • A campaign will only serve if all targeting conditions are met.
    • Example: Campaign targeting (Segment = VIP) AND (Gender = Female).

    From a developer perspective → troubleshooting requires checking all fields (segments, gender, age, placement, etc.).

  • No Partial Matching Beyond IDs

    • GoWit does not perform fuzzy matching or hierarchy across IDs.
    • Example: If you have “Gold,” “Silver,” “Bronze” segments → a campaign targeting “Gold” will not include “Silver” users.
    • You must explicitly target each segment or create a combined segment.
    • IDs are treated as opaque labels with no inherent relationship.

Why Segment Targeting Matters​

By structuring campaigns with segment filters, business rules are enforced in ad delivery:

  • Campaigns meant for a certain audience will never leak outside that audience (if segment assignments are correct).
  • Protects user experience (no irrelevant ads).
  • Protects advertiser goals (budget spent only on the right users).