unidays-javascript v1.0.22

UNiDAYS JavaScript Library

This is the JavaScript library for integrating with UNiDAYS. This is to be used for coded integrations. The following documentation provides descriptions of the implementations and examples.

Contents

How to use this code?

Direct Tracking

• Parameters

  • Example Basket

• Example Usage

  • Create Script URL (returns url for use in a script element)
  • Tracking Script Request (performs the web request asynchronously within a script element)
  • Tag Managers and CDN (use this package without including it as a file)
  • Test endpoint

Unit Tests

Contributing

How to use this code

• Download the contents of dist/, choosing between a regular or minified version of the script.
• Alternatively, pull the package from npm, choosing between a regular of minified version of the script within the created modules directory.
• Include this on the post-payment/order-success page of your web project.
• See the example usage section for the type of call you intend to use. Each of these contains an example.

Direct Tracking

Parameters

Here is a description of all available parameters. Which of these you provide are dependent on the agreed contract.

Mandatory parameters

Additional parameters

Note: any of the following parameters to which the value is unknown/inessential should be omitted from calls (assign null). Which of the following values you provide to us will depend on your agreed contract.

Example Basket

Here is an example basket with the fields relating to UNiDAYS tracking parameters.

Example Usage

Below are examples of implementing the different types of integrations. These examples cover coded integrations and include all optional parameters. They are intended as a guideline for implementation.

• Create Script URL (returns url for use in a script element)
• Tracking Script Request (performs the web request asynchronously within a script element)
• Test endpoint

Create Script URL

This is known as our client-script to server integration

Making the call

The method to get the URL to make a client-to-server request with is createScriptUrl(args...). To implement this method, you first need to ensure that you have access to all required transaction details.

Once you have access to this transaction information, create a UnidaysTracking object, providing the mandatory parameters as arguments new UnidaysTracking(partnerId, currency, transactionId, code) and call .createScriptUrl(args...), where the args are the transaction details you have contractually agreed to send to UNiDAYS.

Note: The args passed into createScriptUrl() must all the present and in the correct order, as per the example below. If a value is unknown/inessential, pass null or 0.

Return

A URL will be returned to you which can be used to call the API. If successful a response with a status code of 200 OK will be returned. This will only work with GET requests.

Example

<script type='text/javascript' src='unidays-tracking.js'></script>

<script type='text/javascript'>
    (function (window) {
        // UNiDAYS will provide your partnerId.
        var partnerId = '0LTio6iVNaKj861RM9azJQ==';

        // These must be based on the real values of the transaction.
        var currency = 'GBP';
        var transactionId = 'Order123';
        var code = 'ABC123';

        var orderTotal = 209.00;
        var itemsUnidaysDiscount = 13.00;
        var itemsTax = 34.50;
        var shippingGross = 5.00;
        var shippingDiscount = 3.00;
        var itemsGross = 230.00;
        var itemsOtherDiscount = 10.00;
        var unidaysDiscountPercentage = 10.00;
        var newCustomer = 1;

        // Create a reference to the UnidaysTracking object, passing in your partnerId, currency, transactionId and code.
        var unidays = new UnidaysTracking(partnerId, currency, transactionId, code);

        // Pass in the remaining corresponding transaction details to the createScriptUrl method.
        var url = unidays.createScriptUrl(orderTotal, itemsUnidaysDiscount, itemsTax, shippingGross,
            shippingDiscount, itemsGross, itemsOtherDiscount, unidaysDiscountPercentage, newCustomer);

        // You now have a URL which can be used within a script element to call the API.
    }(window));
</script>

Tracking Script Request

This will create the client-script URL and perform the request to the UNiDAYS Tracking API for you.

Making the call

The method to call the API with a client-script request is trackingScriptRequest(args...). To implement this method, you first need to ensure that you have access to all required transaction details.

Once you have access to this transaction information, create a UnidaysTracking object, providing the mandatory parameters as arguments new UnidaysTracking(partnerId, currency, transactionId, code) and call .trackingScriptRequest(args...), where the args are the transaction details you have contractually agreed to send to UNiDAYS.

Note: The args passed into trackingScriptRequest() must all the present and in the correct order, as per the example below. If a value is unknown/inessential, pass null or 0.

Return

A URL will be created and called for you within a script element. If successful the response should have a status code of 200 OK.

Example

<script type='text/javascript' src='unidays-tracking.js'></script>

<script type='text/javascript'>
    (function (window) {
        // UNiDAYS will provide your partnerId.
        var partnerId = '0LTio6iVNaKj861RM9azJQ==';

        // These must be based on the real values of the transaction.
        var currency = 'GBP';
        var transactionId = 'Order123';
        var code = 'ABC123';

        var orderTotal = 209.00;
        var itemsUnidaysDiscount = 13.00;
        var itemsTax = 34.50;
        var shippingGross = 5.00;
        var shippingDiscount = 3.00;
        var itemsGross = 230.00;
        var itemsOtherDiscount = 10.00;
        var unidaysDiscountPercentage = 10.00;
        var newCustomer = 1;

        // Create a reference to the UnidaysTracking object, passing in your partnerId, currency, transactionId and code.
        var unidays = new UnidaysTracking(partnerId, currency, transactionId, code);

        // Pass in the remaining corresponding transaction details to the trackingScriptRequest method.
        unidays.trackingScriptRequest(orderTotal, itemsUnidaysDiscount, itemsTax, shippingGross,
            shippingDiscount, itemsGross, itemsOtherDiscount, unidaysDiscountPercentage, newCustomer);

        // The method has built the request and performed a request to our API within a script element.
    }(window));
</script>

Test Endpoint

UNiDAYS provide a test-endpoint configuration of the UnidaysTracking object.

Return

The UnidaysTracking object, configured in test mode, will add an extra parameter (&Test=True) to the URL that is returned to you, or sent for you.

Example

<script type='text/javascript' src='unidays-tracking.js'></script>

<script type='text/javascript'>
    (function (window) {
        // UNiDAYS will provide your partnerId.
        var partnerId = '0LTio6iVNaKj861RM9azJQ==';

        // These must be based on the real values of the transaction.
        var currency = 'GBP';
        var transactionId = 'Order123';
        var code = 'ABC123';

        var orderTotal = 209.00;
        var itemsUnidaysDiscount = 13.00;
        var itemsTax = 34.50;
        var shippingGross = 5.00;
        var shippingDiscount = 3.00;
        var itemsGross = 230.00;
        var itemsOtherDiscount = 10.00;
        var unidaysDiscountPercentage = 10.00;
        var newCustomer = 1;

        // Create a reference to the UnidaysTracking object, passing an additional argument of true to instantiate in test mode.
        var unidays = new UnidaysTracking(partnerId, currency, transactionId, code, true);

        // Pass in the remaining corresponding transaction details to the createScriptUrl method.
        var url = unidays.createScriptUrl(orderTotal, itemsUnidaysDiscount, itemsTax, shippingGross,
            shippingDiscount, itemsGross, itemsOtherDiscount, unidaysDiscountPercentage, newCustomer);

        // You now have a script URL which can be used to test your implementation.
    }(window));
</script>

Tag Managers and CDN

This will demonstrate how to use this Javascript helper within a Tag (e.g. Google Tag Manager or other similar CMS) and/or how to pull in the UNiDAYS Javascript client helper through our CDN.

Note: We have included the SHA384 in the example below; file integrity is guaranteed, so you can be assured that you are always pulling in the official UNiDAYS JavaScript helper.

However, if your Tag Manager or CMS does not support the integrity attribute within <script> elements, simply remove the integrity and crossorigin attributes.

e.g.

<script src="https://cdn.unidays.world/unidays-tracking.min.js"></script>

Making the call

The method to call the API with a client-script request is trackingScriptRequest(args...). To implement this method, you first need to ensure that you have access to all required transaction details. In Google Tag Manager, for example, all of the required transaction information should be already available within the Data Layer for your online store. If any required information is not already available within the Data Layer for your online store, please contact your Development team and ensure this information has been added.

Once you have access to this transaction information, create a UnidaysTracking object, providing the mandatory parameters as arguments new UnidaysTracking(partnerId, currency, transactionId, code) and call .trackingScriptRequest(args...), where the args are the transaction details you have contractually agreed to send to UNiDAYS.

Note: The args passed into trackingScriptRequest() must all the present and in the correct order, as per the example below. If a value is unknown/inessential, pass null or 0.

Note: Most Tag Manangers (such as Google Tag Manager) requires you to reference Data Layer / User-Defined variables using {{This Syntax}} or something similar. If you are unsure, please contact your Development team associated with the Tag Manager platform you use.

Return

A URL will be created and called for you within a script element. If successful the response should have a status code of 200 OK.

Example

<script src="https://cdn.unidays.world/unidays-tracking.min.js"
    integrity="sha384-bUvPj5fOb894FDlGsAUHEdp1F9DILx2A5Kiq0abipj7QpjClwoO9iFSWnZvVhn2q"
    crossorigin="anonymous"></script>

<script type='text/javascript'>
    (function (window) {
        // UNiDAYS will provide your partnerId and signingKey.
        var partnerId = '0LTio6iVNaKj861RM9azJQ==';

        // These must be based on the real values of the transaction. (e.g. For Google Tag Manager, please reference your Data Layer)
        var currency = 'GBP';
        var transactionId = 'Order123';
        var code = 'ABC123';

        var orderTotal = 209.00;
        var itemsUnidaysDiscount = 13.00;
        var itemsTax = 34.50;
        var shippingGross = 5.00;
        var shippingDiscount = 3.00;
        var itemsGross = 230.00;
        var itemsOtherDiscount = 10.00;
        var unidaysDiscountPercentage = 10.00;
        var newCustomer = 1;

        // Create a reference to the UnidaysTracking object, passing in your partnerId, currency, transactionId and code.
        var unidays = new UnidaysTracking(partnerId, currency, transactionId, code);

        // Pass in the remaining corresponding transaction details to the trackingScriptRequest method.
        unidays.trackingScriptRequest(orderTotal, itemsUnidaysDiscount, itemsTax, shippingGross,
            shippingDiscount, itemsGross, itemsOtherDiscount, unidaysDiscountPercentage, newCustomer);

        // The method has built the request and performed a request to our API within a script element.
    }(window));
</script>

Unit Tests

We use Jest for our Unit Tests

Installation

To install the Jest test-runner and all dependencies for this project, run npm install from your favourite terminal within the project directory.

Running the tests

To run the tests, run npm test from your favourite terminal within the project directory.

Contributing

This project is set up as an open source project. As such, if there are any suggestions that you have for features, for improving the code itself, or you have come across any problems; you can raise them and/or suggest changes in implementation.

If you are interested in contributing to this codebase, please follow the contributing guidelines. This contains guides on both contributing directly and raising feature requests or bug reports. Please adhere to our code of conduct when doing any of the above.