Tipser Script SDK

The Tipser SDK is a modular version of the Tipser script that provides only the core functionality necessary for integration with Tipser, specifically built for customers who have their own development resources and plan to build their shopping experience on their own.

Installation

Using npm

You can add the Tipser SDK to your project by adding it through npm.

Yarn:

yarn add @tipser/tipser-sdk

NPM:

npm install --save @tipser/tipser-sdk

Package instructions: https://www.npmjs.com/package/@tipser/tipser-sdk

Using a script tag on your page

Add a script to your page:

<script src="https://cdn.tipser.com/tipser-sdk/latest.js"></script>

Initialization

const tipser = TipserSDK(posId:string, options: object): TipserSDK;

Arguments:

posId (string) - id of shop's account in Tipser (required)

options (object) - an object of options (optional). The same options are supported as for Tipser Widget (docs), except of userid option that is provided as a first argument here

Returns:

Initialized Tipser SDK object that can be used to perform API calls further in this document.

Example:

var tipser = TipserSDK("5aa12d639d25800ff0e56fc5", {primaryColor: "yellow"});

The Example above connects Tipser SDK with Burda shop and sets primary color to yellow.

CUstomizing Tipser environment

By default, Tipser SDK connects to production Tipser environment. Yet if testing environment is preferred (e.g. in order to do test purchase), then it can be customized with env parameter in TipserSDK options, which accepts the following values:

  • prod or production
  • stage or staging
  • dev or development

Example:

var tipser = TipserSDK("5aa12d639d25800ff0e56fc5", {env: "stage"});

Parameters for dialog customization

Sometimes Tipser dialogue styling and functionality needs to be customized. It is possible with modalUi parameters group.

Complete example of dialog customizations:

    var tipserOptions = {
       modalUi: {
          hideSearchIcon: true,
          hideFavouritesIcon: true,
          hideCartIcon: false,
          hideMoreIcon: true,
          hideSimilarProducts: false,
          useCustomCss: true
       }
        });

Hiding icons on menu bar

The following parameters under modalUi can be used to selectively hide tipser icons on the dialog menu bar:

  • hideSearchIcon
  • hideFavouritesIcon
  • hideCartIcon
  • hideMoreIcon

Hiding Similar Products Module

Similarly, hideSimilarProducts parameter, if set to true, can be used to hide Similar Products Module on product page

Custom CSS

If there is a need to use custom css stylesheet, it may be activated in two steps:

1. set useCustomCss parameter to true:

    var tipserOptions = {
            modalUi: {
               useCustomCss: true
            }
    });

2. Send the custom css stylesheet to Tipser administrator in order to be uploaded to your account.

The Script API

Getting cart size

getCurrentCartSize(): Promise<number>

Returns current tipser cart size (including items added to cart from other shops). That value can change over time, so it may be needed to call it repeatedly (polling) to have always up-to-date cart size.

Returns:

A Promise returning current Tipser cart size.

Example:

tipser.getCurrentCartSize().then((cartSize) => {
   console.log("Tipser cart size is: ", cartSize);
   useCartSize(cartSize);
});


Adding product to cart

addToCart(productId: string, options: {posData?: string}): Promise<void>

Adds a product with a given productId (specific to Tipser) to a cart.

productId: is the variant productId, constructed from the masterProductId and the variantId, concatenated with an underscore "_". The productId should look like this <masterProductId>_<variantId>

options: currently the only supported option is posData, which is a string to be attached to a product order. The posData string passed here is returned with other order fields from Tipser commissions API. Warning: maximal number of characters in posData is limited to 4000 characters and will be truncated if longer string is passed.

Returns:

A Promise that resolves to no value but gives a chance to check if the request was successful or not (using .then()/.catch() semantics)

Example:

tipser.addToCart("5a98be67c0bdfb0c30865609_5a98be67c0bdfb0c30866509")
  .then(() => console.log("successfuly added to cart"))
  .catch((err) => console.log("failed to add to cart", err))

Opening product dialogue

openProductDialog(productId: string): void

Opens Tipser product dialog for a product with given tipser product id.

Example:

tipser.openProductDialog("5a16534aa5af9b3af450c33d_5a16537da5af9b3af450c33f");


Opening purchase dialog

openPurchaseDialog(): void

Opens Tipser purchase (checkout) dialog with products that are currently in the shopping cart.


Direct to Checkout

By using the method Direct To Checkout, you add a product to the cart, at the same time as you open the checkout dialogue window.

openDirectToCheckoutDialog(productId: string, options: {posData?: string}): void

Adds the product with a given id to the shopping cart and then opens Tipser purchase (checkout) dialog with products that are currently in the shopping cart (including the newly added product).

productId: is the variant productId, constructed from the masterProductId and the variantId, concatenated with an underscore "_". The productId should look like this <masterProductId>_<variantId>

options: currently the only supported option is posData, which is a string to be attached to a product order. The posData string passed here is returned with other order fields from Tipser commissions API. Warning: maximal number of characters in posData is limited to 4000 characters and will be truncated if longer string is passed.

Opening search dialog

openSearchDialog(searchTerm: string): void

Opens Tipser product search dialog with using a given search term.


Opening collection dialog

openCollectionDialog(shopName: string, collectionName: string): void

Opens Tipser collection browsing dialog for a given Tipser shop name and collection name.


Closing Tipser dialog

closeDialog(): void

Closes the active Tipser dialog.

Listening to analyticS events

addTrackEventListener(listener: (event) => void)
removeTrackEventListener(listener: (event) => void)

The listener callback is called every time payment analytics event (like product dialog opened or product added to cart) is fired by Tipser code.

Listening to dialogue closed event

addDialogClosedListener(listener: (event) => void)
removeDialogClosedListener(listener: (event) => void)

The listener callback is called when every type of Tipser Dialog is closed (including "Thank You page" dialog - in this case both dialogClosed and thankYouPageClosed listeners will be called).

Listening to thank you page closed event

addThankYouPageClosedListener(listener: (orderId: number) => void)
removeThankYouPageClosedListener(listener: (orderId: number) => void)

The listener callback is called when payment confirmation dialog (thank you page) is closed by the user. orderId of the order is passed as a callback argument.

Complete Tipser SDK example

var tipser = TipserSDK("5aa12d639d25800ff0e56fc5", {
   primaryColor: "yellow",
   modalUi: {
      hideSearchIcon: true,
      hideFavouritesIcon: true,
      hideCartIcon: true,
      hideMoreIcon: true,
      useCustomCss: true
   }
});
tipser.getCurrentCartSize().then((cartSize) => {
   console.log("cartSize = ", cartSize);
});
tipser.openProductDialog("5a16534aa5af9b3af450c33d_5a16537da5af9b3af450c33f");

tipser.addTrackEventListener(function(evt) {
    console.log("analytics event: ", evt);
});
tipser.addThankYouPageClosedListener(function() {
    console.log("thank you page closed event");
});

setTimeout(() => {
   tipser.closeDialog();
}, 5000);

The code snippet above initializes tipser SDK with custom primary color and some modal customizations, gets and prints the current cart size, opens a tipser dialog and then closes it after 5 seconds.