The Affelios Connect library is used for connecting your brand to the Affelios platform.
You can install this sdk via NPM or directly from our CDN.
npm install @affelios/platform-connect[!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.5.js"/>[!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'
});
// ...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
clickKeythen you may want to specify additional options.const affelios = new Affelios.Connect({ clickHandler: { clickKeyQueryParameter: 'yourCustomQueryParameter' } }).clickHandler;
[!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
});[!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: '',
defaultTrackerId: '', // 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: 'trackerId', // optional override
productIdQueryParameter: 'productId', // optional override
mediaIdQueryParameter: 'mediaId', // optional override
// optional organic tracking, can forcibly disable by specifying false or providing an organicTrackerId
// organicTracking: false,
// organicTracking: {
// organicTrackerId: '',
// }
}
};
</script>
<script src="https://js.affelios.com/platform-connect/platform-connect.0.0.0-alpha.5.js"/>[!IMPORTANT] AdTracking can be sent manually or configured automatically by passing
affeliosTrack=truethrough the URL query parameters. Automatic tracking is only enabled if theparallelTrackingconfiguration option is enabled or by passing theTrackerconfiguration before initializing the script.
If you're using Google Tag Manager to handle ad tracking, follow the steps below:
- Click add new tag and give it a name
- Click on tag configuration and click custom HTML tag
- Copy and paste the code below
- Edit the
Trackerconfiguration options for your program. - Save and submit the newly created tag to your site.
<script>
(function(d,s){
window.Affelios = {
Tracker: {
operatorId: '',
brandId: '',
defaultTrackerId: '', // 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: 'trackerId', // optional override
productIdQueryParameter: 'productId', // optional override
mediaIdQueryParameter: 'mediaId', // optional override
// optional organic tracking, can forcibly disable by specifying false or providing an organicTrackerId
// organicTracking: false,
// organicTracking: {
// organicTrackerId: '',
// }
}
};
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.5.js";
m.parentNode.insertBefore(e,m);
})(document,'script');
</script>| parameter | type | required | default | notes |
|---|---|---|---|---|
| operatorId | string | ✅ | ||
| brandId | string | ✅ | ||
| 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.trackerId | string | ❌ | ||
| adHandler.productId | string | ❌ | ||
| adHandler.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 | ❌ | trackerId | If this value cannot be found via URL query string parameter, it will fall back to using the defaultTrackerId config value. |
| adHandler.productIdQueryParameter | string | ❌ | productId | 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 | ❌ | mediaId | 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 |
| adHandler.organicTracking.organicTrackerId | string | ✅ | Specify your organic tracker ID to enable organic tracking. |
-
dev- Start the development server -
prebuild- Will download theswagger.jsonfile 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
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.
This SDK was created under the LGPL-2.1 license.