Advanced Concepts

Getting Tipser ids

πŸ“˜

To run Tipser Elements components you will need to pass productId or collectionId. To get productId, log in to app.tipser.com using your publisher's account, find a product in "Insert Products" section, click on the "<>" sign and copy it's productId.
To curate a collection click "+" sign on a product tile and type the name of the collection. Then click "add". Your product is added to the collection. When all the products are added to the collection, click "<" on the right side of the site and then "<>" to copy the the collectionId.

Publisher data

In order to associate a piece of data owned by the publisher with an order item in Tipser, you can use a concept called posData. A posData is an arbitrary string that can be used to store additional information (e.g. session id, user id in your system, etc) attached to order in Tipser's database.
After the transaction is finalized, the string passed as posData will be available back in the response from the Purchase Data API that can be consumed by your backend code (e.g. reporting systems).

πŸ“˜

Because posData is treated as a string in the Tipser system, then if you need to store a structured data (a common use case), please call JSON.stringify() function on a JS object before passing it to Tipser (see: the examples below) and parse it back to JS object when receiving it back.

There are two ways to enable posData:

Option 1: As a global configuration setting that is passed to Elements/SDK initialization (good for static data, like the release number):

const tipserConfig = { posData: "release_2.1.5" };

Option 2: After Elements/Script initialization with updateConfig(posData: string) function (useful for
the data that is not yet available at the time of initialization):

in Tipser Script:

const someData = JSON.stringify({sessionId: "5fa01be88b51", userId: "5fa01bfd3be2"});

tipserScript.updateConfig({posData: someData});

in Tipser Elements:

Just update the value passed to the config prop of TipserElementsProvider in the next render cycle:

const someData = JSON.stringify({sessionId: "5fa01be88b51", userId: "5fa01bfd3be2"});
const elementsConfigWithPosData = {...baseElementsConfig, posData: someData};

return <TipserElementsProvider config={elementsConfigWithPosData}>
...
</TipserElementsProvider>

This will apply for the next and all the subsequent products added to cart.

πŸ“˜

The timing of calling setPosData is relevant. The posData is being sent in the Tipser backend with the add to cart API request. This means that to have any effect, setPosData needs to be called before the product is added to cart (either from the API or by user's action).

❗️

Warning: for performance reasons, the number of characters in posData is limited to 4000. Longer strings will be truncated down to 4000 characters.

Checkout submit functions

You can access the checkout context and create custom functions for submitting delivery and billing address forms as
well as Stripe payment details.

To access the checkout context, create an event listener attached to your checkout wrapper (the element with data-tipser-modular-checkout attribute):

const modularCheckoutElement = document.querySelector('[data-tipser-modular-checkout]');
let getCheckoutContext = null;

modularCheckoutElement.addEventListener('checkout-context-ready', (evt) => {
  getCheckoutContext = evt.detail.getCheckoutContext;
});

Now create your custom submit button, eg:

<button id="submit-button" onclick="handleSubmit()">Submit</button>

and define your submit delivery address function:

const handleSubmit = () => {
    const checkoutContext = getCheckoutContext();
  // for delivery addres submition use:
    checkoutContext.addresses.deliveryAddressForm.submit();
  // for billing address submition use:
    checkoutContext.addresses.billingAddressForm.submit();
  // for payment submition use:
    checkoutContext.payment.paymentForm.submit();
};

Native apps

Tipser Elements is a web-based library and currently we don't provide a native version for Android or iOS (let us know if you'd like us to build it for you!)

However it is possible to embed Elements in a native app if you are using WebViews. We recommend you to follow one of the patterns described below.

Pattern 1: Full web integration

In case your articles are managed by a Web CMS and are displayed in WebView you can simply install and use Tipser Elements in your web articles. Just follow the instructions from Tipser Script or Tipser Elements sections, depending on your technology of choice.

The only customization that we recommend is using customUrls.productUrl configuration, as described below.

Replacing dialogs with redirects

By default, when a product tile is clicked, it opens a full screen product dialog. It may not be desired behavior in your mobile app. Set the configuration option: customUrls.productUrl to a URL containing your product page. That way pressing the back button will bring the user back to your article.

Pattern 2: API integration

If you want to deliver native experience to your users, you can build your custom native e-commerce components (product tiles, shopping cart icon, etc) and use Tipser Rest API to populate them. With this pattern, only the checkout part needs to be displayed in a WebView.

Below is a basic example of a native view with a single product that opens Tipser checkout view when clicked.

Step 1: Rendering a product on your page

  1. Use the Tipser product API to get the product that you want to sell, e.g: https://api.dev.tipser.com/v3/products/5d932be284da04000116ae3c?pos=59e86b79b8f3f60a94ecd26a
    (please, replace the example product id with the desired product and the pos parameter with your own POS id)
  2. Render your custom product component based on the response data

πŸ“˜

Here we describe displaying a single product. If you'd be interested to render multiple products, it's best to use the collections API.

Step2: Opening the checkout view

  1. Create a WebView screen in your app project
  2. When your product is clicked, open the WebView with the URL like: https://www.tipser.com/direct-checkout?productId=productId&posId=59e86b79b8f3f60a94ecd26a
    (again, please make sure to replace the posId with your POS id and productId with the Tipser id of the product that was clicked)

πŸ“˜

If your use case is not covered in this section, please discuss it with Tipser technical support.

Versioning

Tipser Script follows Semantic Versioning.

The recommended "evergreen" https://cdn.tipser.com/tipser-script/v3/tipser-script.min.js distribution of Tipser Script fetches to the most recent version of the code published by Tipser every time the user loads the page.

πŸ“˜

This means that some slight changes in the behaviour might be automatically enabled on your site when the new version of Tipser Script is available, but this also means that any improvements and bug fixes will be applied on your site in a shorter time.

If you prefer, you can fix your stick to a specific version of Tipser Script by using URL schema like https://cdn.tipser.com/tipser-script/v3.0.24/tipser-script.min.js (please note how v3 part was replaced with a specific version: v3.0.24 in this example).

🚧

Breaking changes limitation

When updates are made to Tipser Script, we check to ensure no breaking changes are included within the releases. This is why we recommend fetching https://cdn.tipser.com/tipser-script/v3/tipser-script.min.js to ensure you have the latest version.