Use BigQuery as a source — audience targeting

To target visitors by data that lives in BigQuery, Kameleoon reads that data on a schedule. A Data Ingestion Task runs a SQL query on your BigQuery project at a frequency you set, and Kameleoon imports the visitors that the query returns. The query must return a visitor_id column that matches the identifier your code passes to Kameleoon. You can then target campaigns at those visitors using data that already sits in your warehouse. Before you begin, enable the BigQuery integration for your project. Then follow these steps to import audience data and use it in your campaigns.

1. Activate the feature: In the selected project’s configuration, check the checkbox labeled Use BigQuery as a source to enable the feature.
2. Create a Data Ingestion Task: Click Add new task, then complete the form.
3. Save the configuration: After you create your tasks, click Validate to save and apply your configuration settings.

4. Create custom data: Kameleoon polls your warehouse at the frequency you set. To use the collected data in targeting, create custom data for it.
5. Create a segment: Create a segment that uses the custom data, then target it in your campaigns.

​

Data Ingestion Tasks

A Data Ingestion Task runs a SQL query against your BigQuery project at a frequency you set. You can create several tasks, and each task has its own query and frequency. If a poll fails, Kameleoon logs the failure, and the audience keeps the membership from the last successful poll until a later poll succeeds.

​

Creating a Data Ingestion Task

Create a Data Ingestion Task to start importing audience data from BigQuery.

1. Click Add new task.

2. Complete the form:
   1. Name (required): Give your task a unique and descriptive name to identify its purpose.
   2. Frequency (required): Specify how often you want the task to run and retrieve data from BigQuery (for example, per day).
   3. BigQuery project ID (required): Provide the project ID associated with your Google BigQuery project.
   4. Region (required): Select the appropriate region from the provided list. The region selection specifies the geographical location for your BigQuery operations (available regions).
   5. Query (required): Provide the SQL query that retrieves the audience from your BigQuery database. The query must follow this specific format: SELECT visitor_id, attribute_1, ..., attribute_N FROM your_events_table

The attribute_ fields are optional. Use them for advanced targeting scenarios, which Target your imported audiences describes. The visitor_id column holds the identifier Kameleoon uses to look up each visitor’s audience data. Use the same value you pass when you retrieve the audience in your code, which is either the Kameleoon visitor code or, if you pass one, your own warehouseKey. For guidance on choosing an identifier, see Visitor identification. Provide all the required information, then click Confirm to create the Data Ingestion Task. Kameleoon starts polling your warehouse when you create a task, and the data is available for targeting right away. You can use the polled data through the Activation API for web experiments, or through Kameleoon’s SDKs for Feature Experimentation.

​

Guidelines

Column naming

Column names can only contain letters (uppercase or lowercase), numbers, and underscores (_). They can’t start with a number.

Column order

The columns must appear in the exact order specified (visitor_id, followed by optional attributes) for the integration to function correctly.

​

Run your query before ingestion

While you create or edit a task, you can test your query directly in Kameleoon. Testing allows you to:

• Verify the connection in real time.
• Confirm your credentials and access rights are correct, which helps detect issues immediately, without having to wait for the first data import.
• Validate your data’s structure and accessibility.

You can run a simple query to ensure Kameleoon can access the right databases and tables. You can also download a small sample of the dataset to confirm that the schema, permissions, and contents match your expectations.

​

Updating a Data Ingestion Task

Edit a Data Ingestion Task to change its name, frequency, BigQuery project ID, region, or query.

1. Select the task: Begin by selecting the specific Data Ingestion Task you want to edit from the dropdown menu.

2. Edit task details: Modify the fields you want to update, such as the task’s name, frequency, BigQuery project ID, region, or query.
3. Confirm changes: After making the necessary updates, click Confirm to save the changes to the Data Ingestion Task.

​

Deleting a Data Ingestion Task

Delete a Data Ingestion Task that you no longer need. Before you delete a task, delete its associated custom data. The app shows a warning before you confirm the deletion.

1. Select the task: Choose the Data Ingestion Task you wish to delete from the dropdown menu.
2. Initiate deletion: Click Delete data ingestion task in the edit form.
3. Confirm deletion: A confirmation prompt appears. Click Confirm to delete the selected Data Ingestion Task.

​

Targeting your imported audiences

Each Data Ingestion Task defines an audience, and you target that audience through a custom data entry and a segment. Choose the approach that matches what you want to target:

• A pre-built audience: For example, all visitors born in London. Create one custom data entry that lists every Ingestion Task audience, then build a segment from it.
• A visitor attribute: For example, the city where each visitor was born, with many different values. Add the attribute as a field after visitor_id in your query, then create a custom data entry that holds its value.

The method that reads the custom data depends on the product. Feature Experimentation alone uses the Kameleoon SDK method. Web Experimentation, alone or alongside Feature Experimentation, uses custom JavaScript code. For the setup steps and code samples for each approach, see Target your imported audiences.