generated: '2026-08-12' method: searched source: >- Field-by-field from the provider's own published references — https://github.com/socialvibe/truex-ads-docs/blob/master/web_service_ad_api.md (ad object, callback parameters), reporting_api.md (report record), js_ad_api.md (engagement object, terminology) and engagement_interaction_tracking.md (interaction shape). derived_from: docs derived_from_note: >- NOT derived from an OpenAPI — true[X] publishes none. Every entity, field and relationship below appears verbatim in a provider reference table or a provider sample payload. No field is inferred and no entity is invented. entities: - name: placement aka: - placement_hash - identifier hash - partner_config_hash (deprecated) id_field: placement_hash description: >- A unique alphanumeric identifier generated by true[X]. Each integrating publisher placement has its own hash. It is the primary tenancy key across every surface — ad requests, reporting rows and engagement callbacks all key on it. fields: - name: placement_hash type: string - name: placement_name type: string source: reporting - name: placement.key type: string note: The request-parameter spelling of placement_hash on the Web Service Ad API. appears_in: - web-service-ad-api request - reporting-api response - engagement callback - name: ad aka: - creative - activity - engagement (informally) id_field: id description: >- The rich-media ad unit true[X] returns for a placement. The Web Service Ad API returns exactly one ad object per successful request. fields: - name: id type: integer description: Unique identifier of the ad creative, defined by true[X]. - name: campaign_id type: integer description: Unique identifier of the ad campaign. - name: name type: string description: Name of the ad creative. - name: window_url type: string description: The URL that renders the ad. - name: window_width type: integer - name: window_height type: integer - name: currency_amount type: integer description: Publisher currency the user earns for completing this ad. - name: revenue_amount type: string description: Revenue to be earned by the partner for this ad. - name: session_id type: string description: Unique identifier for the current session, assigned by true[X]. appears_in: - web-service-ad-api response - js-ad-api requestAd callback - name: campaign id_field: campaign_id description: >- An advertiser campaign. Reporting is broken out by campaign within placement within day. fields: - name: campaign_id type: integer - name: campaign_name type: string - name: campaign_start_date type: string format: YYYY-MM-DD - name: campaign_end_date type: string format: YYYY-MM-DD - name: daily_frequency_cap type: integer - name: lifetime_frequency_cap type: integer - name: cap_type type: string examples: - units - value_added_units - name: country_targets type: string format: comma-separated - name: state_targets type: string format: comma-separated - name: dma_targets type: string format: comma-separated - name: postal_code_targets type: string format: comma-separated appears_in: - reporting-api response - engagement callback - name: creative id_field: creative_id description: >- The specific creative executed within a campaign. Distinct from campaign in the callback payload, where both ids and both names are sent. fields: - name: creative_id type: string - name: creative_name type: string appears_in: - engagement callback - name: user id_field: user.id aka: - network_user_id (deprecated) description: >- A partner-provided alphanumeric string uniquely identifying the current user; the platform advertising ID is recommended where supported. true[X] never mints the user id — the publisher owns it. fields: - name: user.id type: string - name: age type: integer optional: true - name: yob type: integer optional: true note: Year of birth as a 4-digit integer; alternative to age. - name: gender type: string enum: - m - f - x - name: coppa type: boolean values: - '1' - '0' note: Pass 1 if the user is under 13; prevents data storing. - name: ip type: string note: Required on server-side calls; used for geo-targeting. - name: user_agent type: string note: Required on server-side calls; URI encoded. - name: dimension_1 .. dimension_5 type: string note: Five free-form targetable metadata slots. appears_in: - web-service-ad-api request - engagement callback - name: session id_field: session_id description: >- Assigned by true[X] per ad session and returned on the ad object. Ties an ad delivery to the interactions and the eventual engagement. appears_in: - web-service-ad-api response - name: engagement id_field: engagement_id description: >- The record true[X] creates internally when a user completes an ad — True Attention met, meaning roughly 30 seconds spent plus at least one interaction. This is the billing event: the advertiser is billed and the publisher earns its per-unit payment. engagement_id is also the deduplication key on the callback. fields: - name: engagement_id type: string - name: currency_amount type: integer - name: currency_label type: string examples: - coins - name: revenue type: decimal note: Up to 8 decimal places. - name: application_key type: string - name: sig type: string note: HMAC-SHA1 signature of the callback. appears_in: - engagement callback - js-ad-api onCredit callback - name: interaction description: >- A tracked user or container action inside an engagement. Not exposed on any read API — emitted as tracking beacons and surfaced in aggregate through reporting. fields: - name: category type: string enum: - timing - multimedia - navigation - external_page - click - other - share - data_entry - aggregate - debug - name: name type: string - name: value type: string optional: true - name: step type: integer optional: true - name: user_initiated type: boolean appears_in: - tracking beacons - name: performance_report_record description: >- One row of the Reporting API response, uniquely addressed by the composite key placement_hash + day + campaign_id. composite_key: - placement_hash - day - campaign_id fields: - name: day type: string format: YYYY-MM-DD - name: company type: string - name: initial_engagements type: integer - name: completed_engagements type: integer - name: advertiser_cost type: string - name: average_cpe type: string - name: net_revenue type: string appears_in: - reporting-api response relationships: - from: placement to: ad type: has_many via: placement.key note: A placement requests ads; each request returns at most one ad. - from: campaign to: ad type: has_many via: campaign_id - from: campaign to: creative type: has_many via: creative_id - from: ad to: campaign type: belongs_to via: campaign_id - from: ad to: session type: has_one via: session_id - from: session to: engagement type: has_one via: engagement_id note: An engagement is created only if the user reaches True Attention. - from: engagement to: user type: belongs_to via: network_user_id - from: engagement to: placement type: belongs_to via: placement_hash - from: engagement to: campaign type: belongs_to via: campaign_id - from: engagement to: creative type: belongs_to via: creative_id - from: engagement to: interaction type: has_many via: session - from: performance_report_record to: placement type: belongs_to via: placement_hash - from: performance_report_record to: campaign type: belongs_to via: campaign_id id_conventions: numeric: - ad.id - campaign_id opaque_string: - placement_hash - session_id - engagement_id - request_id note: >- No typed id prefixes (no cus_/ch_ style namespacing). Numeric ids and opaque base64url-ish strings are mixed across the same payloads, and the same logical id is typed as integer in the ad object and as string in the callback payload (campaign_id, creative_id). gaps: - No object reference page; entities must be reconstructed from parameter tables. - Inconsistent typing of the same id across surfaces (integer vs string). - No read API for interactions, engagements or sessions — only aggregate reporting. - No schema document (JSON Schema, OpenAPI components) of any kind.