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 productionstage
or stagingdev
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.