Pinpoll SDK Documentation

Welcome to the Pinpoll Universe.

Important: Before using our SDK please contact us at support@pinpoll.com and tell us your domain where you are planning to use it, otherwise it will not work. Please make sure that your visitors have obtained a visitor cookie from Pinpoll before executing the Pinpoll SDK. Visitors cookies can be obtained by loading our global script (included in global.js or pa.js) before the SDK.

Getting Started

To use our SDK please add the following snippet inside your <head> block of your homepage.

<script src="https://cdn.pinpoll.com/sdk.js" async></script>

This script will add the class PinpollSdk to the window object.

Usage

Now you can test if a connection to the Pinpoll SDK is working by executing our test method ping().

window.addEventListener('load', function() {
    PinpollSdk.ping();
});

An info message should appear in your console: PinpollSdk: pong!

Use Cases

Currently we are supporting the following use cases:

Add Audiences

Add audiences (with optional affinity score) to the current visitor with knowledge which you collected by other tools. These audiences will be then added to the Pinpoll Universe and shown in any Pinpoll Analytics View (up to 30 days backwards). Please create your audience first in Pinpoll DMP and remember the id of the audience or use an existing Pinpoll Audience. All audience ids can be determined by calling our Analytics API.

Hint: The affinity score is the probability, how likely the visitor is matching to the given audience, where 1 is the lowest and 10 is the highest. If there is no affinity score provided a default score of 1 will be taken.

Example

window.addEventListener('load', function() {
    var sdk = new PinpollSdk();

    var firstAudience = {id: 5, affinityScore: 7};
    sdk.addAudience(firstAudience);
    
    // some other calls
    // ...
    
    var secondAudience = {id: 1020, affinityScore: 7};
    sdk.addAudience(secondAudience);

    // publish data
    sdk.sendData();
});

Remove Audiences

Analogue to adding audiences it is also possible to remove audiences from the current visitor with knowledge which you collected by other tools. These audiences will be then removed from the visitor in the Pinpoll Universe and shown in any Pinpoll Analytics View (up to 30 days backwards). All audience ids can be determined by calling our Analytics API.

A typical use case would be usually to remove one (old) audience and add another (new) one. For example if your visitor upgraded to a premium subscription you want to remove the audience 'Standard Subscription' and add the audience 'Premium Subscription' to the given visitor.

Example

window.addEventListener('load', function() {
    var sdk = new PinpollSdk();

    var audienceToRemove = {id: 5}; // Audience: Standard Subscription
    sdk.removeAudience(audienceToRemove);

    var audienceToAdd = {id: 6, affinityScore: 10}; // Audience: Premium Subscription
    sdk.addAudience(audienceToAdd);

    // publish data
    sdk.sendData();
});

Add Custom Attributes

Add your custom attributes to the current visitor. Currently we are supporting the following fields:

userId (String)
email (String)

Please contact us at support@pinpoll.com if you need further custom fields.

A common use case would be to add a userId to the current visitor. Once added you can query interesting insights about that specific user including visited pages with their timestamp and the visitors audiences without having knowledge of the visitor cookie by calling our Analytics API.

Example

window.addEventListener('load', function() {
    var sdk = new PinpollSdk();
    
    var attributes = {
        userId: '123',
        email: 'john.doe@pinpoll.com',
    };
    sdk.setAttributes(attributes);

     // publish data
    sdk.sendData();
});

Get Audiences of Current Visitor

Get all audiences of the current visitor as json document, divided in interests and properties.

This data can be used by further tools (Advertising, Analytics, Content Recommendation, ...) on your homepage. For example if the current visitor is a sports enthusiast, with specific interest in Beach-Volleyball, why not recommend him an article about the latests Beach-Volleyball results in his region, or show him a special offer of buying the newest Mikasa Ball VLS 300?

Example

window.addEventListener('load', function() {
    var sdk = new PinpollSdk();

    // optional options
    var options = {
        tree: true,
        removeRootLevel: 'none',
        onlyLabels: 'en'
    }
    sdk.getAudiences(options).then(function(audiences) {
        // Do something with the collected audiences
        console.log(audiences);
    }).catch(function (error) {
        console.error(error);
    });
});

Track Event of Current Visitor

Track an event with an specific event name of the current visitor.

Event tracking is useful if you want to track certain events a visitor made on your website. For example if you want track how many visitors signed up for a category (Sports, Economics, etc.) You can visualize your collected data in Pinpoll Analytics via our event tracking widget on the realtime page.

You can add more information to your event with the additional value and label parameters. value allows you to track any numeric metric you want to associate with the event. The label allows you to split one event into multiple categories.

Example

window.addEventListener('load', function() {
    // It's possible to specify only the event name
    // or a key value pair with event name and event value

    // Example 1: Only with event name
    var eventName = 'signup_sports';

    PinpollSdk.trackEvent(eventName);

    // Example 2: With event name and value
    var eventName = 'purchase';
    var value = 40.5;

    PinpollSdk.trackEvent(eventName, value);

    // Example 3: With event name and value and label
    var eventName = 'purchase';
    var value = 40.5;
    var label = 'electronics';

    PinpollSdk.trackEvent(eventName, value, label);
});

A detailed API definition of all currently available methods and their parameters can be found on the sidebar.

Info

Our SDK is supporting all browsers including IE 11. However, all examples are written in a syntax by using promises. To support also IE 11 and older browser versions make sure to include a polyfill for promises on your homepage.

Example

<script src="https://cdn.jsdelivr.net/npm/promise-polyfill@8/dist/polyfill.min.js"></script>

Alternatively you can use the service from https://polyfill.io/.

Questions?

If you have any further question please don't hesitate to contact us at support@pinpoll.com.

This SDK is still Work In Progress, so we cannot guarantee (yet) that there will be no breaking changes in the following versions.