Skip to content

User & Domain Entities in the Beacon Ecosystem

This guide explains the data structures and operational roles of the User and Domain entities within the Social Signal Beacon ecosystem. Partners use these entities via the Partner API to provision clients, configure tracking thresholds, allocate credits, and define custom delivery pipelines.

1. User Entity

The User entity represents a partner's client account. It functions as the root container for identity, overall subscription plan state, API keys, and fallback event handling logic.

Canonical Schema (PartnerUser)

Field Type Description
_id string User Client ID: The unique identifier for the user account (e.g., user_123).
pid string Partner ID: The reselling partner who owns/provisioned this client.
email string Primary contact and authentication email for the user.
company string (optional) Name of the client's business/dealership.
status enum Lifecycle state: pending, active, suspended, or archived.
domains array[string] List of active domains registered to this user account.
defaultVisitFlow object (optional) Fallback programmatic Hono flow template to run on visitor traffic.
defaultLeadFlow object (optional) Fallback flow template to execute when a lead match is resolved.

Operational Role in Beacon

  • Quota & Billing: Houses the billing parameters and holds credit pools.
  • Logical Fallbacks: If a domain does not specify custom pipelines (visitFlow/leadFlow), the system falls back to the User's defaultVisitFlow and defaultLeadFlow configuration.
  • Access Control: Contains the API key used by the client for direct integrations.

2. Domain Entity

The Domain entity represents a single website hostname registered under a client User. It controls script enablement, visit matching criteria, credit allocations, and third-party CRM integration coordinates.

Canonical Schema (PartnerDomain)

Field Type Default Description
_id string - User Client ID: Links the domain configuration back to the parent User record.
domain string - Domain Name: Clean host URL (e.g., dealername.com, parsed of subpaths/protocols).
pid string - Partner ID matching the parent user.
enablement boolean false Indicates whether beacon script event tracking is active.
status enum active Lifecycle status: pending, active, suspended, or archived.
collectLeads boolean false Read-only flag: Indicates if lead matching is currently authorized and running.
instantCredits integer 0 One-time credits allocated for identity lookup operations (only values of 0 or 10 are accepted; other values default to 0).
weeklyCredits integer 0 Recurring credits automatically refilled each week.
monthlyCredits integer 0 Recurring credits automatically refilled each month (must be one of: 0, 75, 250, 1000, 2500).
minVisitsToMatch integer 2 Minimum visitor visit-count threshold to trigger lead matching.
visitFlow object null Programmatic flow template executed immediately on a new visitor hit.
leadFlow object null Programmatic flow template executed once a visitor's identity is resolved (matched).
metadata object {} Key-value settings for third-party endpoints (e.g. CRM credentials).

Operational Role in Beacon

  • Traffic Validation: When the script makes a request to the edge endpoint /api/v2/beacon/event, the gateway verifies the domain is active and has enablement: true.
  • Visit Filtering: The minVisitsToMatch setting filters out casual single-page bounces. The visitor profile must register at least this many visits before the edge initiates a lead resolution query.
  • Credit Ingress: Resolving a lead consumes credits. The lookup checks the domain's combined credit balances (instantCredits + recurring balances) before initiating the match.
  • Delivery Integration: The leadFlow defines where resolved leads are sent (e.g., pushed to CRM webhooks, dispatched to Slack, or emailed).

3. Interaction Flow Overview

The diagram below details how the User, Domain, and Beacon services interact during visitor event processing:

sequenceDiagram
    autonumber
    actor Visitor as Eyeball/Visitor
    participant Edge as Edge Gateway (ssedge)
    participant KV as BRecord Cache (KV)
    participant Engine as FlowRunner (ssmono)
    participant CRM as Partner CRM / Email

    Visitor->>Edge: Hits website (sends Beacon Event)
    Edge->>KV: Look up Domain (enablement & status)
    KV-->>Edge: Returns Domain configuration
    Edge->>KV: Look up Parent User (status & credentials)
    KV-->>Edge: Returns User record

    alt Validation Fails (Disabled/Suspended)
        Edge-->>Visitor: 204 No Content (Drop Silent)
    else Validation Succeeds
        Edge->>KV: Log Visit & Increment Visit Count
        alt Visits < minVisitsToMatch
            Edge-->>Visitor: 200 OK (Awaiting Threshold)
        else Visits >= minVisitsToMatch
            Edge->>Engine: Trigger Lead Resolution (consume credit)
            Engine->>Engine: Run Domain.leadFlow (or User.defaultLeadFlow)
            Engine->>CRM: Deliver formatted lead payload
            Edge-->>Visitor: 200 OK (Lead Pushed)
        end
    end