Skip to main content

Privacy Guide

This guide describes privacy best practices when integrating the In-Chat Recommendations API.

It focuses on:

  • What data is sent to the API
  • What developers should / should not include
  • Recommended controls to reduce privacy risk
  • Logging, storage, and transparency guidance

This guide is intended for engineering implementation. It does not replace your company’s legal review.

1) Data Flow Overview​

What the integration does​

  1. Your app sends a request to the In-Chat Recommendations API.
  2. The API responds with a list of recommended ads (documents[]) plus a tracking endpoint (tracking.reportServed).
  3. Your UI renders one or more ads.
  4. Your client fires the impression pixel once ads are visible using:
    • tracking.reportServed + &pos=X-Y

2) What Data You Send​

A) Query parameters (required)​

These identify the integration and the page context:

  • key — API key identifying your integration
  • contentUrl — host page the chat experience is running on
  • widgetJSId — Teads-provided widget identifier
  • cors=true
  • testMode=true (optional, for development)

✅ Guidance:

  • Only send the host page or canonical URL for contentUrl
  • Ensure it is URL-encoded where needed

❌ Avoid:

  • URLs containing sensitive path/query fragments (e.g., /account/12345, ?email=user@...)

B) JSON body (contextual signals)​

This provides real-time intent signals from the chat:

{
  "keywords": ["investing", "savings", "personal finance"],
  "iabCategories": ["IAB13"]
}

✅ Recommended:

  • High-level intent keywords
  • Broad contextual topics (e.g., “travel”, “insurance”, “banking”)
  • IAB categories that map the conversation context

❌ Do not include:

  • Full chat transcripts
  • Names, emails, phone numbers
  • Postal addresses
  • Account IDs, user IDs, order IDs, session IDs
  • Health status, diagnoses, or extremely sensitive topics
  • Political affiliation, religious identity, sexual orientation
  • Any “free text” directly copied from the user without filtering

Best practice: treat keywords as topic labels, not raw user text.

3) Personally Identifiable Information (PII) Rules​

Never send PII in requests​

PII includes (but is not limited to):

  • Name + identifier (e.g., “John Smith from Acme”)
  • Email address
  • Phone number
  • Precise location (street address)
  • Government IDs
  • Payment details

✅ If you need personalization:

  • Use non-identifying interest signals (keywords/categories)
  • Keep signals coarse and contextual

4) Sensitive Content Rules​

In general, avoid sending signals derived from:

  • Medical conditions / health
  • Minors or child-related profiling
  • Financial hardship (e.g., debt status tied to a specific user)
  • Legal trouble or criminal accusations
  • Highly personal relationship issues

✅ If your product supports sensitive conversations:

  • Use a safe category mapping (e.g., “wellness” instead of “diagnosis”)
  • Apply extra filtering before generating keywords

5) Minimization + Filtering Recommendations​

A) Keyword safety filter​

Before sending keywords, apply:

  • PII redaction (emails, phone numbers, addresses)
  • Blocklist patterns:
    • numbers that look like IDs
    • “my SSN is…”
    • “my credit card…”
  • Length limits (e.g., max 3–10 keywords)

B) Keep signals short-lived​

  • Generate keywords from current session context
  • Avoid building long-lived profiles unless you have explicit user consent

C) Prefer taxonomy mapping​

If possible:

  • Derive iabCategories from your own classification system
  • Use keywords only as a secondary hint

6) Logging + Storage Guidance​

Client-side / server-side logs​

✅ Recommended:

  • Log only request success/failure
  • Log response metadata needed for debugging (e.g., HTTP status)

❌ Avoid logging:

  • The full request body with keywords if they might be sensitive
  • Full response payloads containing URLs and creatives
  • Full reportServed tokenized URLs in persistent logs

Best practice: If you must log, mask sensitive values:

  • key
  • tracking tokens / URLs
  • any contextual signals

Retention​

  • Keep logs for the minimum duration needed (e.g., 7–30 days)
  • Follow your org’s retention policies

7) Transparency to End Users​

✅ Recommended UI transparency:

  • Clearly label ads as Sponsored
  • Show the advertiser name
  • Optionally show the advertiser domain (target_domain)
  • Provide an accessible “Why am I seeing this?” entry where relevant

Example disclosure string:

“Sponsored by example brand”

8) Impression Pixel (reportServed) Privacy Notes​

The pixel is required for monetization and should be fired only when ads are rendered.

✅ Good practice:

  • Fire only for positions (pos) actually displayed
  • Fire once per render event where possible
  • Use navigator.sendBeacon() client-side when available

❌ Avoid:

  • Adding user identifiers to the pixel URL
  • Appending extra query parameters that contain personal data

Pixel format reminder:

{tracking.reportServed}&pos=0-2

9) Security Best Practices​

✅ API key handling:

  • Treat key as a secret
  • Do not expose it in public repos
  • Rotate keys if compromised

✅ Transport:

  • Always use HTTPS (default for this endpoint)

✅ Input validation:

  • Validate contentUrl is in an allowed list (or matches your domain)
  • Ensure keywords is a safe sanitized array of strings

10) Development Checklist​

Use this checklist before launch:

  • contentUrl contains no PII (no sensitive path/query)
  • keywords are topic labels, not raw user messages
  • PII filtering is applied before sending requests
  • No persistent logging of keywords/chat content
  • Impression pixel fires only for displayed ads (pos)
  • Ads are clearly marked as Sponsored
  • API key stored securely and rotated as needed

11) Example “Safe Keywords” vs “Unsafe Keywords”​

✅ Safe:

  • ["travel deals", "ski vacations", "all inclusive resorts"]
  • ["credit cards", "budgeting", "investing"]

❌ Unsafe:

  • ["John Smith", "my email is john@email.com"]
  • ["I live at 12 Main Street"]
  • ["my bank account number 1234..."]

If you'd like, I can also provide:

  • a PII redaction snippet (JS + Python)
  • a sample keyword extraction strategy that avoids user-text leakage