@affelios/platform-connect v0.0.0-alpha.9
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 theparallelTracking
configuration option is enabled or by passing theTracker
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 serverprebuild
- Will download theswagger.json
file and build the type definitionsbuild
- Build for productionrelease
- Generate changelog and npm publishlint
- Checks your code for any linting errorstest
- Run all teststest:watch
- Run all tests with watch modetest:coverage
- Run all tests with code coverage reportprepare
- 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.
11 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago