The Tipser script explained

The script controls the full appearance and behaviour of the Image tagging, Get the Look and Embedded shop on a site where it is installed. The script needs to be placed on the page where the shop and image tagging should appear. The collections in the shop and the products in the collections are managed from the profile page on tipser.com, through the Tipser Tools or through native editing tools on platforms where Tipser is integrated.

Note! You need to be logged in at tipser.com in order for the administration functionality to work properly.

Running the script

The script should be run on your page, and ideally be placed in the HTML code (in the footer) just above the </BODY> tag on the page where it should appear. The script can be loaded at any time and will react to tagged images, collections or shop insertion points. The script runs asynchronously and should not block any other scripts running on the parent page, however the script will start to download images once the product tiles are inserted into the DOM, and may then affect the

The script can also be distributed by e.g. Google Tag manager.

The bare minimum to initiate the script

<script>
// Load Tipser asynchronously
(function(d, s, id){
  var js,tjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) {return;}
  js = d.createElement(s); js.async = true; js.id = id;
  js.src = '//www.tipser.com/widget/widget.js';
  js.onload = js.onreadystatechange = function() {
    var rs = this.readyState;
    if (rs && rs != 'complete' && rs != 'loaded') return; try {
      tipser = new Tipser({
        userid:'<Insert the Tipser user ID>'
        });
      tipser.start();
      }
      catch (e) {}};
    tjs.parentNode.insertBefore(js, tjs);
}(document, 'script', 'tipser-js'));
</script>

The script is personalised for the site owner which is controlled by the Tipser User ID:

userid:'<Insert the Tipser user ID>'

The user ID can be picked up from: https://www.tipser.com/profile/tools

Technical prerequisites and software requirements

Tipser embeddable shopping is designed to work in all contemporary web devices. This means that support for browsers is limited to all latest stable versions of IE, Edge, Chrome, Safari, Firefox and one version before of each (that is: IE 10+, Edge 16+, Firefox 59+, Chrome 65+, Safari 10+). Tipser also guarantees to work in protected mode (Incognito/private mode), but in that setup some functionalities, such as user session persistence may not work in specific browser configurations, when user chooses to disable any 1st/3rd party tracking code.

Tipser embeddable shopping integrates tightly with your page. Since Tipser code is running on your page to handle collections, products, shopping cart and checkout, it is possible that your page's code may affect the Tipser's correct functioning. It is required not to perform any invasive/destructive operations on window.Tipser/window.TipserWidget objects or remove/modify any of the Tipser code (collections, modals, shopping cart, post messages event listeners etc.).

It is possible to run Tipser in non-static pages, such as Single-Page Apps or interactive webapps embedded into the viewport, as well as Tipser works well when used right with React/Angular/similar frontend frameworks, as long as the Tipser script is properly included once. Make sure that your web application does not remove Fragment identifier that come from Tipser (all that begins with Tipser), namely: Tipser_ThankYou and Tipser_Checkout) as this is required for the actual purchase transaction to be correctly handled by the Tipser.

Configuring your store UI

The embedded store can be configured in a number of ways to better suit the needs of the site owner.

Either by inserting parameters in the loading script, or by adding data- tags to the HTML that marks where collections, or the shop is be rendered.

tipser = new Tipser({
  userid:'<Insert the Tipser user ID>',
  <FURTHER PARAMETERS>

});

Language and Market

These parameters control the default language and market for the widget. A user can manually select another available language from the language menu, and then the default language will be overridden in the user interface.

Market (optional) controls the currency, and ship-to country. If this parameter is missing, the market value is inherited from DefaultLang parameter (but can't inherit value en).


Available markets are

DefaultLang controls the default language

And the parameters to control the market and language:

market: 'sv',
defaultLang: 'en'

In the above example market is swedish, but the default language of the widget is english.

Primary color

The primary color parameter can control the experience of buy buttons, and key elements in the UI. The color should be in the HEX format.

primaryColor: '#E91E63'

Parameters for the shop

These parameters control the default settings for the embedded shop, which can also be controlled from the shop HTML. Parameters set in the shop HTML data properties overwrite these default settings.

The HTML to be used to mark the position of the shop is id="tipser_shop"

<div id="tipser_shop"></div>

The parameters to control the shop UI is

shop: {
  menuPosition: "top" // top, left
  hideFooter: false // hides the footer
}

Menu Position

Sets the menu position in the shop DIV.

menuPosition: "left", // left or top (default)

The equivalent data property to control the setting is data-tipser-menu-position.

<div id="tipser_shop" data-tipser-menu-position="left"></div>

Footer

Hides the footer in the shop DIV.

hideFooter: false,

The equivalent data property to control the setting is data-tipser-footer.

<div id="tipser_shop" data-tipser-footer="false"></div>

Parameters for the embedded collections, GTL

Sets the default behaviour for product view for the inserted collections (Get the looks), which can also be controlled from the HTML directly through data properties. Parameters set in the HTML overwrite these default settings.

The HTML to be used to mark the position of the collectiont is class="tipser-pCol"
<div data-tipser-cid="509277de5c3d093978b31721" class="tipser-pCol"></div>
gtl: {
  hideText: "slide" // Hides the text in GTL collections
  imgSize: 1.2 // 0.8 small, 1.2 large
}

Hide the product text

Sets the default behaviour for product view for the inserted collections (Get the looks). "Slide" slides up the text over the product image. False keeps it visible at all times.

hideText: "slide", // slide or false

The equivalent data property to control the setting is data-tipser-hide-text.

<div data-tipser-cid="509277de5c3d093978b31721" class="tipser-pCol" data-tipser-hide-text="slide"></div>

false:

The product text is always visible.

slide:

The product text is hidden, until the mouse hovers the image and the text slides up from below.

Image Size

Sets the default behaviour for product view for the inserted collections (Get the looks). The size parameter affects the image size in the product tiles. 1 is the normal case, and 0.8 makes them small and 1.2 makes them large, and 2 XXL.

imgSize: 1.2,

The equivalent data property to control the setting is data-tipser-imgsize.

<div data-tipser-cid="509277de5c3d093978b31721" class="tipser-pCol" data-tipser-imgsize="1.5"></div>

Dialogue position

Parameters for the dialogue popup. By setting the parameters you can control the size of the popup.

position: {
  left:'10px',
  right:'10px',
  top:'10px',
  bottom:'10px',
  minWidth:'300px',
  minHeight:'200px'
},

The cart tab

The shopping cart tab is controlled by the tab parameters.

tab: {
  pos: 0 // 1= top right, 2= bottom right, 3= bottom left, 4= top left, 0= middle right
  hide: false
}

Tab position

Controls the position of the shopping cart tab. The parameter is optional and only needs to be set if the tab should be moved to another position on the page. For mobile phones, it's always in the bottom right corner.

position: 0 (default) // 1= top right, 2= bottom right, 3= bottom left, 4= top left, 0= middle right

Hide the shopping tab

Controls the visibility of the shopping cart tab. The parameter is optional and only needs to be set if the tab should be hidden on the site.

hide: true (default) // false

Parameters for image tagging

The image tagger scans for suitable objects on a page to tag on page load, or after new DOM elements are injected into the page. By default it is scanning for <IMG> objects, and overlays already tagged images with a floater making it clear that it is an active image.

The image tagger has default settings for min and max size of the images that are accepted as suitable objects to tag.

Taggable images

The imageMinXXX parameter tells the script what minimum size (in pixels) the image should be for the script to accept it.

taggable: {
  imageMinWidth : 150, // min width in px 
  imageMaxWidth : 2500, // max width in px 
  imageMinHeight :150, // min height in px
  imageMaxHeight :2500, // max height in px 
},

Image Id Attribute

By setting the imageIdAttribute the image tagging can identify images based on a custom attribute in the <IMG> tag instead of the image URL itself. This is useful when different versions of images are loaded based on the screen resolution.

imageIdAttribute: '<attribute>',

Example:

//Attribute setting

imageIdAttribute: 'data-timg',

//HTML example

<img data-timg=”12345” src=””>

Image Id Base

Namespace for attribute id to ensure the uniqueness of the attribute IDs used in the image tag to prevent the image to be falsely tagging the wrong image.

imageIdBase: 'mysite.com',

Excluding images for image tagging

The excludeurls parameter tells the script what URLs to skip in the scanning process. This can be useful if there are images used as design elements that should not be possible to tag. More URLs can be inserted with a comma that is separating the URLs. The full path to the URL is neede

excludeurls:[];

Example:

excludeurls:['http:tipser.com/image.jpg','...'];

Attach Floater

The attachFloater parameter tells the system to mark images as tagged with the default floater image.

attachFloater: true (default) / false

Parameters for dialog customization

Sometimes tipser dialog stlyling 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.

Inserting the shop and the collection into your HTML

How to insert the shop

The shop is inserted into the web page where the marker ID is located on the page

Insert the target ID tipser_shop where the script shall render the shop:

<div id="tipser_shop"></div>

The shop can be configured with a left or top menu as well as smaller or larger images, to best suit your page design.

How to insert product collections on a page

The product collection is rendered where the script finds the class tipser-pCol in combination with a valid collection ID in the data object data-tipser-cid="<COLLECTION ID>"

See the following example code that will display the content of the collection Gold.

<p name="Gold" data-tipser-cid="509277de5c3d093978b31721" class="tipser-pCol"><a href="https://www.tipser.com/shops/jonas/gold" class="tipser-pCol-link">Gold</a></p>
http://www.damernasvarld.se/kronprinsessan-victoria-stralar-i-svensk-design-shoppa-looken-har/

Note, that you can use any HTML element for the collection, like P, DIV, etc.

Tipser custom events tw-*

The Tipser script emits custom events - tw-* - that can be used to build custom actions on top of.

You can listen to these events by setting up a custom event listener on your page, such as this example:

document.addEventListener('tw-script-ready', function() {
  //Your custom code...
  console.log("tipser script ready");
});,

Script loaded

The Tipser script emits a tw-script-ready event when the Tipser widget script is finished loading, and all components have been initialised.

Analytics

The Tipser script emits tw-track events for many activities where the Tipser shopping solution is used. More details about the different message bodies can be found on the Tipser Analytics page.

Dialogue actions

The Tipser script emits a tw-thank-you-page-closed event when the Tipser widget thank you window is closed (after a purchase is made).

Tipser script API

The Tipser script actions can be triggered using the script API. The script API is accessed by POST message commands.

Example:

window.top.postMessage({
command: "tipser.api.displayProduct",
  productId: "588bfc00101bf58e446c8f55"
}, '*');

Open product window

The Tipser product widget window can be opened by the command tipser.api.displayProduct with the argument productId.

Example:

window.top.postMessage({
  command: "tipser.api.displayProduct",
  productId: "588bfc00101bf58e446c8f55"
}, '*');

Open checkout window

The Tipser checkout widget window can be opened by the command tipser.api.purchase with no arguments. The product form the current shopping cart will be displayed in the window.

Example:

window.top.postMessage({
  command: "tipser.api.purchase"
}, '*');

Direct to checkout

The Tipser checkout widget window can be opened, and the product added to the cart in one go by the command tipser.api.directToCheckout with the argument productId.

Example:

window.top.postMessage({
  command: "tipser.api. directToCheckout",
  productId: "588bfc00101bf58e446c8f55"
}, '*');

Open collection window

The Tipser collection widget window (shop collection) can be opened by the command tipser.api. openCollection with the argument shopName and collectionName . Both being text strings.

Example:

window.top.postMessage({
  command: "tipser.api.openCollection",
  shopName: "tipser",
  collectionName: "my-new-collection"
}, '*');

Open search window

The Tipser product search widget window can be opened by the command tipser.api.openSearch with the argument search.

Example:

window.top.postMessage({
  command: "tipser.api.openSearch",
  search: "Marimekko"
}, '*');

Troubleshooting

For developers so, you can understand what’s happening in the script

debug: true, // write log-messages to :
debugType: 'console' // 'console' / 'alert', never use this except for mobiles

For the latest questions and support go to http://kundo.se/org/tipser/