@affelios/platform-connect NPM

Affelios-Platform-Connect-JavaScript

The Affelios Connect library is used for connecting your brand to the Affelios platform.

Get started

Installation

You can install this sdk via NPM or directly from our CDN.

NPM

npm install @affelios/platform-connect

CDN

!IMPORTANT This script tag should be placed within the <head> of your HTML document.

<script src="https://js.affelios.com/platform-connect/platform-connect.0.0.0-alpha.9.js"/>

Usage

Pixel Integration (Insecure)

!CAUTION This method is not secure, this is intended to be used on platforms where a full integration is not possible or the user has no programming experience.

const affelios = new Affelios.Connect({ operatorId: 'yourOperatorId', brandId: 'yourBrandId' }).pixel;
affelios.createCustomer({
    externalId: '123',
    country_code: 'GB',
    username: 'SuperCoolUser'
});
affelios.createTransaction({
    externalId: '123',
    country_code: 'GB',
    depositAmount: 1.00,
    grossRevenue: 1.00,
    externalCustomerId: 'SuperCoolUser',
    externalProductId: '123'
});
// ...

Storing click keys (frontend)

In order for Affelios to detect the click key and store it within the cookie, you must include the snippet below within your codebase.

const affelios = new Affelios.Connect().clickHandler;

!WARNING If you are using a query parameter different from clickKey then you may want to specify additional options.
const affelios = new Affelios.Connect({
   clickHandler: {
       clickKeyQueryParameter: 'yourCustomQueryParameter'
   }
}).clickHandler;

Retrieving click keys (backend)

!IMPORTANT This method is the most secure, if you are using this method, you should not use the Pixel integration method, instead you should call the Affelios API to create the customer and transactions from your backend.

Once you've integrated the click handler into the front-end, the click key will be available to you via cookies. If you're using express for example, to access the cookie, you're required to parse this value from the HTTP cookies. You can use a simple package like cookie-parser to achieve this, below is an example:

import express from 'express';
import cookieParser from 'cookie-parser';

const app = express();

app.use(cookieParser());

app.post('/user/register', (req, res) => {
    const clickKey = req.cookies.clickKey; // If you are using a custom cookie name, then you'll want to change `clickKey`

    // Store the click key along with the registration
});

Ad Tracking Integration

!WARNING AdTracking is only enabled if the adHandler's required configuration values are provided.

You can enable ad tracking in 2 ways, the first method is to create an instance of the script and passing the adHandler's configuration values, or alternatively you can declare the Tracker configuration before the script is referenced. You can do this with the following code snippet below:

<script>
    window.Affelios = {
        Tracker: {
            operatorId: '',
            brandId: '',
            customDomains: {
                clickUrl: 'https://track.affapp.io'
            },
            defaults: {
                trackerId: '', // fallback (will attempt to retrieve the trackerId from URL query parameters before falling back)
                productId: '', // optional (will attempt to retrieve the productId from URL query parameters)
                mediaId: '', // optional (will attempt to retrieve the mediaId from URL query parameters)
            },
            clickKeyQueryParameter: 'gclid', // optional (defaults to clickKey)
            keywordQueryParameter: 'keyword', // optional override
            trackerIdQueryParameter: 'cid', // optional override
            productIdQueryParameter: 'pid', // optional override
            mediaIdQueryParameter: 'mid', // optional override
            // optional organic tracking, can forcibly disable by specifying false or providing a trackerId, this will override any defaults set.
            // organicTracking: false,
            // organicTracking: {
            //     trackerId: '',
            // }
        }
    };
</script>
<script src="https://js.affelios.com/platform-connect/platform-connect.0.0.0-alpha.9.js"/>

!IMPORTANT AdTracking can be sent manually or configured automatically by passing affeliosTrack=true through the URL query parameters. Automatic tracking is only enabled if the parallelTracking configuration option is enabled or by passing the Tracker configuration before initializing the script.

Setup Ad Tracking with Google Tag Manager

If you're using Google Tag Manager to handle ad tracking, follow the steps below: 1. Click add new tag and give it a name 2. Click on tag configuration and click custom HTML tag 3. Copy and paste the code below 4. Edit the Tracker configuration options for your program. 5. Save and submit the newly created tag to your site.

<script>
    (function(d,s){
        window.Affelios = {
            Tracker: {
                operatorId: '',
                brandId: '',
                customDomains: {
                    clickUrl: 'https://track.affapp.io'
                },
                defaults: {
                    trackerId: '', // fallback (will attempt to retrieve the trackerId from URL query parameters before falling back)
                    productId: '', // optional (will attempt to retrieve the productId from URL query parameters)
                    mediaId: '', // optional (will attempt to retrieve the mediaId from URL query parameters)
                },
                clickKeyQueryParameter: 'gclid', // optional (defaults to clickKey)
                keywordQueryParameter: 'keyword', // optional override
                trackerIdQueryParameter: 'cid', // optional override
                productIdQueryParameter: 'pid', // optional override
                mediaIdQueryParameter: 'mid', // optional override
                // optional organic tracking, can forcibly disable by specifying false or providing a trackerId, this will override any defaults set.
                // organicTracking: false,
                // organicTracking: {
                //     trackerId: '',
                // }
            }
        };
        var e = d.createElement(s),
        m = d.getElementsByTagName(s)[0];
        e.async = 1;
        e.src = "https://js.affelios.com/platform-connect/platform-connect.0.0.0-alpha.9.js";
        m.parentNode.insertBefore(e,m);
    })(document,'script');
</script>

Options

parameter	type	required	default	notes
operatorId	string	✅
brandId	string	✅
customDomains.clickUrl	string	❌	https://track.affapp.io	If you wish to use a custom click domain that you have configured in Affelios, you can also set that to be used using this parameter.
clickHandler	object \| false	❌		If you disable the clickHandler, you will have to pass the clickKey value directly through to pixel integration functions. You should avoid disabling this unless you know what you're doing.
clickHandler.cookie	object	❌
clickHandler.cookie.name	string	❌	clickKey
clickHandler.cookie.expirationInDays	number	❌	30
clickHandler.clickKeyQueryParameter	string	❌	clickKey
adHandler	object	❌		By default, the adHandler is disabled unless it's required values are provided.
adHandler.parallelTracking	boolean	❌	false	If you enable this option, tracking data will only be sent if the `affeliosTrack` URL query parameter is set to true.
adHandler.defaults.trackerId	string	❌
adHandler.defaults.productId	string	❌
adHandler.defaults.mediaId	string	❌
adHandler.clickKeyQueryParameter	string	❌	clickKey	If this parameter is not passed, then it chooses the default specified under the clickHandler.
adHandler.keywordQueryParameter	string	❌	keyword
adHandler.trackerIdQueryParameter	string	❌	cid	If this value cannot be found via URL query string parameter, it will fall back to using the defaultTrackerId config value.
adHandler.productIdQueryParameter	string	❌	pid	If this value cannot be found via URL query string parameter, it will fall back to using the productId config value if provided.
adHandler.mediaIdQueryParameter	string	❌	mid	If this value cannot be found via URL query string parameter, it will fall back to using the mediaId config value if provided.
adHandler.organicTracking	boolean	object	❌	false	If you wish to enable organic tracking, you can pass it's sub parameters as an object.
adHandler.organicTracking.organicTrackerId	string	✅		Specify your organic tracker ID to enable organic tracking.

Development

dev - Start the development server
prebuild - Will download the swagger.json file and build the type definitions
build - Build for production
release - Generate changelog and npm publish
lint - Checks your code for any linting errors
test - Run all tests
test:watch - Run all tests with watch mode
test:coverage - Run all tests with code coverage report
prepare - Script for setting up husky hooks