0.0.0-alpha.9 • Published 11 months ago

@affelios/platform-connect v0.0.0-alpha.9

Weekly downloads
-
License
LGPL-2.1-or-later
Repository
github
Last release
11 months ago

Affelios Logo

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

parametertyperequireddefaultnotes
operatorIdstring
brandIdstring
customDomains.clickUrlstringhttps://track.affapp.ioIf 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.
clickHandlerobject | falseIf 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.cookieobject
clickHandler.cookie.namestringclickKey
clickHandler.cookie.expirationInDaysnumber30
clickHandler.clickKeyQueryParameterstringclickKey
adHandlerobjectBy default, the adHandler is disabled unless it's required values are provided.
adHandler.parallelTrackingbooleanfalseIf you enable this option, tracking data will only be sent if the affeliosTrack URL query parameter is set to true.
adHandler.defaults.trackerIdstring
adHandler.defaults.productIdstring
adHandler.defaults.mediaIdstring
adHandler.clickKeyQueryParameterstringclickKeyIf this parameter is not passed, then it chooses the default specified under the clickHandler.
adHandler.keywordQueryParameterstringkeyword
adHandler.trackerIdQueryParameterstringcidIf this value cannot be found via URL query string parameter, it will fall back to using the defaultTrackerId config value.
adHandler.productIdQueryParameterstringpidIf this value cannot be found via URL query string parameter, it will fall back to using the productId config value if provided.
adHandler.mediaIdQueryParameterstringmidIf this value cannot be found via URL query string parameter, it will fall back to using the mediaId config value if provided.
adHandler.organicTrackingbooleanobjectfalseIf you wish to enable organic tracking, you can pass it's sub parameters as an object.
adHandler.organicTracking.organicTrackerIdstringSpecify 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

Build

To build the library, run the npm run build command.

To use the library in a browser, you'd need to import the platform-connect.umd.cjs script.

If you're using this in anything other than a browser, then you can use platform-connect.cjs.

License

This SDK was created under the LGPL-2.1 license.

0.0.0-alpha.9

11 months ago

0.0.0-alpha.8

12 months ago

0.0.0-alpha.7

12 months ago

0.0.0-alpha.6

12 months ago

0.0.0-alpha.5

1 year ago

0.0.0-alpha.4

1 year ago

0.0.0-alpha.3

1 year ago

0.0.0-alpha.2

1 year ago

0.0.0-alpha.1

1 year ago

0.0.0-alpha.0

1 year ago