Piwik PRO Audiences

Piwik PRO groups your visitors into audiences that you define in Piwik PRO, which the scripts in this article call segments. Kameleoon can’t use those audiences until each visitor’s segments reach your Kameleoon project. This integration sets each visitor’s segments as custom data in Kameleoon, so you can select the audiences in a segment and match visitors by them.

​

How Piwik PRO audiences fit into your workflow

• Retrieve the segments: Add the global custom script, so that each visitor’s Piwik PRO segments reach Kameleoon.
• Create the custom data: Create the Piwik PRO segments custom data, and add the list of segments to it.
• Build a segment: Target visitors in one or more Piwik PRO audiences.
• Use the segments in Feature Experimentation: Store each visitor’s segments in Kameleoon, and read them with an SDK.

​

Before you begin

• Piwik PRO account: an active Piwik PRO account with the audiences you want to use.
• Piwik PRO credentials: a client_id and client_secret for generating a bearer token, as described in the Piwik PRO authentication reference. You also need your website_id, which Piwik PRO calls the site or app ID. To find it, read the Piwik PRO help article on site or app IDs. The scripts in this article use only client_id and website_id.
• Piwik PRO tracker: Your site loads the Piwik PRO tracker, which provides the _paq object that the global custom script waits for.
• Kameleoon tag: Your site loads the Kameleoon tag, which provides the Kameleoon.API methods the scripts call.

​

Retrieve Piwik PRO segments for each visitor

The global custom script runs on every page where the Kameleoon tag loads. It waits for the Piwik PRO tracker, and then it requests the visitor’s segments from a Kameleoon web service. The script requests segments only after the tracker loads. If the tracker never loads, the script sets no segments for the visitor.

​

Add the global custom script

Add the script to your project’s global custom script, so that Kameleoon retrieves each visitor’s Piwik PRO segments.

1. Click Admin > Projects, then click Edit on your project’s row.
2. Click the Scripts tab, and then click Edit next to Global custom script.
   
3. Paste the following script into the Global custom script editor, and replace the client_id and website_id placeholders with your values.
   const getPiwikProSegments = (visitorID) => {
       const clientID = 'Replace this with your client_id';
       const websiteID = 'Replace this with your website_id';
       const xhr = new XMLHttpRequest();
       xhr.onload = function run() {
           if (this.status === 200) {
               Kameleoon.API.Data.setCustomData(
                   'Piwik PRO segments',
                   JSON.parse(xhr.response)
               );
           }
       };
       xhr.open('GET', `https://customers.kameleoon.com/kameleoon/piwik/user/${visitorID}?id=${clientID}&website_id=${websiteID}`, true);
       xhr.send();
   };
   
   Kameleoon.API.Core.runWhenConditionTrue(() => typeof _paq !== 'undefined', () => {
       _paq.push([function init() {
           getPiwikProSegments(this.getVisitorId());
       }]);
   });
   
4. Click Save changes.

After a visitor loads a page with the Piwik PRO tracker, the script sets the Piwik PRO segments custom data for that visitor. If the request to the Kameleoon web service fails, the script sets no custom data for that page.

​

Create custom data for the Piwik PRO segments

The custom data has two parts. The global script fills it with each visitor’s segments, and a second script lists every segment as an option in the segment builder. Because the custom data uses the Page scope, Kameleoon resets its value on each new page, so the global script sets the segments again each time a page loads.

​

Create the custom data

Create the custom data that the global script fills with each visitor’s segments.

1. Click Settings > Custom Data, and then click New custom data.
2. Enter Piwik PRO segments as the name, and select your project. The global script sets the custom data by this name, so enter it exactly.
3. Keep Retrieval method set to Kameleoon Activation API, which is the default.
4. Set Type to List, Format to String, and Scope to Page. With the Page scope, Kameleoon resets the value for each new page, and the global script sets it again when the page loads.
5. Click Next to open the options.

Kameleoon saves the custom data when you click Create on the options step.

​

Add the segment list to the custom data

Add the script that returns the Piwik PRO segments as values for the custom data.

1. Turn on Save the values for the targeting condition associated with the custom data point. A code field appears.
2. Paste the following script into the code field, and replace the client_id and website_id placeholders with your values.
   let segmentPW = [];
   const clientID = 'Replace this with your client_id';
   const websiteID = 'Replace this with your website_id';
   
   const xhr = new XMLHttpRequest();
   xhr.onreadystatechange = function check() {
       if (this.readyState === 4) segmentPW = JSON.parse(xhr.response);
   };
   xhr.open('GET', `https://customers.kameleoon.com/kameleoon/piwik/segments/?id=${clientID}&website_id=${websiteID}`, false);
   xhr.send();
   return segmentPW;
   
3. Click Create.

The segment builder lists the Piwik PRO segments as values, so you can select them when you build a segment.

​

Build a segment from Piwik PRO audiences

Build a segment that targets visitors who belong to one or more Piwik PRO audiences.

1. Click Settings > Segments, and then click New segment.
2. In the Conditions column, open the Custom data tab, and then select Piwik PRO segments.
3. Select the is among the values condition, and then select the audiences you want to target.
4. Choose whether to include or exclude the visitors who match the condition.

Kameleoon adds the segment to the Segments list, where you can select it for an experiment or personalization. To learn more about segments, see create a segment.

​

Use Piwik PRO audiences in Feature Experimentation

The global custom script runs in the browser, so the segments it sets aren’t available to feature flags that Kameleoon’s SDKs evaluate. To use Piwik PRO audiences in a feature flag, store each visitor’s segments on Kameleoon’s servers, and then read them with an SDK.

​

Store and read the segments with an SDK

Store each visitor’s segments in Kameleoon, and then set them as custom data in your SDK code.

1. Post each visitor’s segments to the Data API Map endpoint, using the visitor code or a user ID as the key. See the Map endpoint reference.
2. Click Settings > Custom Data, and then click New custom data. Enter a name for the custom data, such as Piwik PRO audiences, and select your project.
3. Set Retrieval method to Kameleoon SDK method, Type to List, and Format to String. Choose the Scope that fits your feature flag.
4. In your SDK code, call getRemoteData() with the visitor code or user ID, read the segments from the returned JSON, and set them with addData().

After the SDK sets the value, the custom data holds the visitor’s segments, which you can select in a segment. For more detail, see use external data to target users.