Chameleon

Sync user profiles and events to Chameleon for personalized in-app experiences, product tours, and tooltips. Zeotap pushes data from your warehouse into Chameleon via their REST API, enabling you to target onboarding flows and product adoption experiences based on your unified customer data.

Prerequisites

• A Chameleon account with API access enabled
• An account secret token generated from the Chameleon dashboard
• User identifiers (UIDs) that match the identifiers used in your Chameleon JavaScript SDK installation

Authentication

Chameleon uses Account Secret Token authentication.

1. Log in to your Chameleon account at app.chameleon.io 
2. Navigate to Settings > Tokens
3. Click Generate New Token
4. Copy the token immediately — it can only be downloaded once
5. Paste it into the Account Secret field in Zeotap

Keep your account secret token secure. It provides full API access to your Chameleon account data. Do not share it in publicly accessible areas.

Configuration

No additional configuration fields are required beyond authentication.

Target Settings

When Object Type is “User Profiles”

User profile data is sent to Chameleon via the batch profiles webhook endpoint. Profiles are created automatically on first sync and updated on subsequent syncs. Custom properties are normalized to lowercase with underscores (e.g., userRole becomes user_role).

When Object Type is “Events”

Events are sent individually to Chameleon and processed asynchronously (typically within 30 seconds). Each event requires a user identifier and event name, with optional custom properties.

Supported Operations

Sync Modes

Audience Sync Modes

Chameleon segments are filter-based and computed dynamically — membership cannot be managed via the API. Use user profile properties to control segment membership indirectly.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

User Profiles

Events

How It Works

User Profile Syncs

1. Zeotap extracts user data from your model or audience
2. Rows are grouped into batches of up to 1,000 profiles
3. Each batch is sent to the Chameleon batch profiles webhook endpoint (POST /v3/observe/hooks/profiles/batch)
4. Profiles are created on first request or updated if they already exist (upsert behavior)
5. Per-item errors from Chameleon are captured and reported individually
6. Custom properties sent alongside standard fields (email, name, etc.) are stored on the user profile

Event Syncs

1. Zeotap extracts event data from your model
2. Each event is sent individually to the Chameleon events webhook endpoint (POST /v3/observe/hooks/events)
3. The uid field identifies the user, and event_name maps to the Chameleon event name
4. Additional mapped fields are sent as custom event properties
5. Events are processed asynchronously by Chameleon, typically within 30 seconds

Rate Limits

Chameleon enforces the following rate limits:

• Global: 60–120 requests per minute across all endpoints
• Max concurrent: Some endpoints limit simultaneous requests (e.g., profile search is limited to 1 concurrent request)
• Batch size: Maximum 16 MB per request; recommended up to 10,000 items per batch

Zeotap automatically handles rate limiting with exponential backoff and respects X-Retry-After and X-Ratelimit-Wait headers. Profile batches are kept at 1,000 items to stay well within limits.

Best Practices

• Ensure the uid values in Zeotap match the identifiers used in your Chameleon JavaScript SDK installation — mismatched UIDs create duplicate profiles
• Use User Profiles object type to enrich user data for targeting tours and microsurveys
• Use Events object type to track backend events that complement client-side event tracking
• Send company_uid alongside user profiles to link users to companies in Chameleon
• Property names are normalized to lowercase with underscores — use consistent naming conventions
• Start with a small sync to verify data mapping before running full syncs
• Use the Upsert sync mode to keep profiles current without duplicating records

Troubleshooting

Authentication failed

Verify your account secret token is valid and has not been revoked. Tokens can be managed in Settings > Tokens in Chameleon. Note that each token can only be downloaded once — if lost, generate a new token.

User profiles not appearing

Ensure the uid field is mapped and contains non-empty values. Chameleon requires at least one identifier (uid, email, or id) to create a profile. Check that the uid values match those used in your Chameleon JavaScript SDK.

Events not appearing

Events are processed asynchronously and typically appear within 30 seconds. Verify that both uid and event_name fields are mapped and contain non-empty values. Check the Chameleon dashboard under Data > Events to confirm receipt.

Rate limit errors (HTTP 429)

Chameleon limits API requests to 60–120 per minute. Zeotap retries automatically with backoff. For persistent rate limit issues, reduce sync frequency or contact Chameleon support to discuss higher limits for your account.

Duplicate user profiles

Duplicate profiles occur when different uid values refer to the same user. Ensure your source data uses consistent user identifiers. Chameleon uses uid as the primary deduplication key.

Custom properties not updating

Property names are normalized to lowercase with underscores (e.g., userRole becomes user_role). Verify the expected property name format in Chameleon. Each property value is limited to 768 bytes — larger values are truncated.

Batch request too large (HTTP 413)

If you see 413 errors, the batch payload exceeds Chameleon’s 16 MB limit. This typically happens with rows containing large text or JSON fields. Reduce the number of fields mapped or filter out rows with oversized values.

Company association not working

To link users to companies, map the company_uid field to your company identifier. The company must either already exist in Chameleon or be created separately. Verify company UIDs are consistent between user and company data.