Segmentation

Segmentation allows publishers to control which users are eligible for specific survey experiences by attaching custom attributes to a participant’s profile.

These attributes are sent during impanelment and can be used to target or restrict access to certain offers.

---

How Segmentation Works

Segmentation is powered by the attributes_hash field on the /players/impanel endpoint.

When a user is impaneled:

1. You send custom attributes via attributes_hash
2. TapResearch stores these attributes on the user profile
3. These attributes are evaluated when determining survey eligibility
4. Only users matching an offer’s targeting rules will qualify ---

Sending Segmentation Data

Segmentation attributes are passed as a JSON object:

{
  "attributes_hash": {
    "is_premium_user": true,
    "subscription_tier": "gold",
    "days_since_signup": 7
  }
}

Supported Value Types

Type	Example
Boolean	true, false
Number	1, 42, 3.14
String	"gold", "us_west"

---

Example Use Cases

Segmentation can be used to target surveys based on internal business logic or user state.

Examples

• Target only new users:

  { "is_new_user": true }

• Segment by subscription tier:

  { "subscription_tier": "premium" }

• Limit surveys to highly engaged users:

  { "days_since_signup": 30 }

• Exclude users who have already completed onboarding:

  { "completed_onboarding": false }

---

How Targeting is Applied

Each offer can be configured with segmentation rules.

When a user requests surveys:

• Their stored attributes are evaluated against available offers
• Only offers with matching criteria are considered eligible
• If no segmentation rules are defined, the offer is available to all users

---

When to Send Attributes

• Attributes should be sent during /players/impanel.
• You may update attributes over time by calling the endpoint again
• Updates take effect immediately for future survey requests

---

Best Practices

• Use clear, consistent naming for keys (e.g. is_premium_user, not premiumFlag)
• Keep attribute values simple and predictable
• Prefer booleans and enums over free-form strings
• Avoid sending sensitive or personally identifiable information (PII)
• Only send attributes that are relevant for targeting decisions

---

Notes

• attributes_hash is optional — if not provided, no segmentation is applied
• Attributes are stored per user and persist across sessions
• Segmentation is evaluated automatically — no additional API calls are required
• Attributes may influence which surveys are returned from /campaigns