This SDK works both client-side in your browser but also server-side in a Node.js environment.
First, you need to create an app allowing you to make API requests. You will be prompted to create a new user first.
We recommend creating 2 apps: 1 for production and another for development. This ensures environments aren't mixed.
The SDK makes use of both JavaScript and CSS so you need to load two resources in the browser:
<link
href="https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.css"
rel="stylesheet"
type="text/css"
/>
<script
src="https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.js"
id="sgn-sdk"
data-api-key="YOUR_API_KEY"
data-track-id="YOUR_TRACK_ID"
></script>
By defining your app key and track identifier as data attributes when including the JavaScript file the SDK auto-configures itself. You can find the app key and track identifier in the developer console.
We recommend you use npm to install the SDK. To install, simply type the following into a terminal window:
npm install shopgun-sdk
When installed you can require and configure the SDK:
SGN = require('shopgun-sdk');
SGN.config.set({
apiKey: 'YOUR_API_KEY'
});
We recommend using environment variables for the config to avoid having secrets in your code base:
SGN.config.set({
apiKey: process.env.SHOPGUN_API_KEY
});
To provide your users with a viewing experience for PDF's you need to use our PagedPublicationKit. We've built an example that shows how it can work.
To learn more about integrating the same experience on iOS and Android be sure to check out the respective SDK's:
To minimize the effort needed in setting this up, we've created some built-in (customizable) templates to list and view your publications.
The setup is almost the same from above, you need to include the CSS and Javascript libraries. However, instead of creating an extra script to render the publication viewer, you only need to add a container and a few more required data-* attributes to render the template. Eg:
<link
href="https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.css"
rel="stylesheet"
type="text/css"
/>
<div id="paged-publication"></div>
<script
data-readme="API's and SDK's by Tjek (https://tjek.com)"
src="https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.js"
id="sgn-sdk"
data-api-key="YOUR_API_KEY"
data-track-id="YOUR_TRACK_ID"
data-business-id="YOUR_BUSINESS_ID"
data-component="paged-publication-viewer"
data-component-publication-container="#paged-publication"
defer
></script>
Below is another example which will render the list of active publications. It will also render the publication viewer upon clicking on a certain publication:
<link
href="https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.css"
rel="stylesheet"
type="text/css"
/>
<div id="list-publications"></div>
<script
data-readme="API's and SDK's by Tjek (https://tjek.com)"
src="https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.js"
id="sgn-sdk"
data-api-key="YOUR_API_KEY"
data-track-id="YOUR_TRACK_ID"
data-business-id="YOUR_BUSINESS_ID"
data-component="list-publications"
data-component-list-publications-container="#list-publications"
defer
></script>
Aside from the required data- attributes, the SDK still support a few more data for customizations
Attribute | Value |
---|---|
data-business-id | Business ID |
data-component |
paged-publication-viewer : To render (default: latest) paged publication viewerincito-publication-viewer : To render incito publication viewerlist-publications : To render the list of active publications. |
data-component-list-publications-container |
#custom_container_id .custom_container_class
|
data-component-publication-container |
#custom_container_id .custom_container_class
|
data-component-list-publications-order-by |
newest (default) oldest
|
data-component-publication-id |
{publication_id} : To render specific publication |
data-locale-code |
en_US (default) da_DK
|
data-component-theme |
light (default)dark
|
data-publication-id-query-param |
id (default) : The page publication viewer can accept query param to display a certain publication. This is to override the default id param |
data-publication-page-query-param |
page (default) : The page publication viewer can accept query param to initially load a certain page. This is to override the default page param |
data-component-publication-display-url-params |
null (default) : No URL params will be displayed hash : publication id and page will be displayed as hash fragment. eg: 'domain.com/#publication/{id}/{page}' query : publication id and page will be displayed as query params. eg: 'domain.com/?publicationid={id}&publicationpage={page}' |
data-publication-hash |
publication (default) : This is to override the default hash value eg: eg: 'domain.com/#publication/{id}/{page}' |
data-component-publications-list-item-click-behavior |
open_publication_viewer (default) : Open publication viewer upon clicking it from the publication list |
data-translation-keys--{key} |
{key} : Any value that will replace the default value per key from the locale files |
data-component-publication-viewer-offer-click-behavior |
shopping_list (default) : Offer will be added to shopping listredirect_to_webshop_link : Clicking an offer will redirect to webshop link; Shopping list will be disabled automaticallyopen_webshop_link_in_tab : Clicking an offer will open webshop link in new tab; Shopping list will be disabled automatically overview_modal : Open modal that shows the offer details |
data-component-publication-disable-shopping-list |
false (default)true
|
data-component-publication-disable-close |
false (default)true
|
data-component-publication-disable-menu |
false (default)true
|
data-component-publication-disable-download |
false (default)true
|
data-component-publication-disable-header |
false (default)true
|
data-component-publication-disable-pagedecorations |
false (default)true
|
data-component-publication-show-header-labels |
false (default)true
|
data-component-publication-override-global-scrollbar |
false (default)true : To disable html scroll on publication reader |
data-component-publication-utm-source |
tjek (default) |
data-component-publication-utm-medium |
referral (default) |
data-component-list-publications-request-filter | eg: r_lat:59.9139,r_lng:10.7522 eg: tags:weekly catalog Filter on request level - key:value and is separated by comma |
data-component-list-publications-client-filter | eg: all_stores:true Filter on client side level - key:value and is separated by comma |
-
PagedPublicationKit
- Page opens are now tracked upon the open rather than upon the close
-
verso-browser
- Add
pointerdown
event
- Add
-
PagedPublicationKit Viewer
- Add new bindable
hotspotsPointerdown
event, the callback to which will receive an array of one or more hotspots under the down pointer. This is useful for doing work before the double-click delay confirms a single-click, such as prefetching.
- Add new bindable
- Remove
incito-browser
hyphenation behavior to prevent line-breaks in offer details - Update dependencies
- Semanatic masked versions are now published on our CDN, this means that you can get all versions of the SDK until we make a breaking change and change the major version like so: https://js-sdk.tjek.com/sgn-sdk-4.x.x.min.js
- Update dependencies
- Fix Incito
data-link
behavior.
- Updated the
incito-browser
library with new and speedy rendering + addedHTMLEmbedView
- Removed sessions from
CoreKit
- Removed some unused config settings such as
locale
andappSecret
- Removed unused code
- Update the
incito-browser
libary with newHTMLView
that adds support for a more complex view component through the use of a style property for valid css style-attributes.
-
Internal refactor to vanilla JS
No breaking changes anticipated but a minor version bump to avoid automagic patches, just in case.
- IncitoPublicationKit: Updated
incito-browser
to 1.1.37
- PagedPublicationKit: Will now use zoom-size images for pages prior to zooming in, when the physical pixel width of the page would be presented as over 700 pixels wide.
- IncitoPublicationKit: Removed sessionStorage caching due to excessive JSON.parse JSON.stringify operations, which slows down the browser.
- PagedPublicationKit: Add a new optional createViewer option
pickHotspot
, which is called when the user presses an intersection of several hotspots. This replaces the default picker popover element. API example:
var viewer = bootstrapper.createViewer(data, {
pickHotspot: function (
// array of hotspots
hotspots,
// event that contains some metadata about the clicked page, viewer and click position
// viewerEvent.verso.x and viewerEvent.verso.y are useful for positioning a picker relative to the viewer
viewerEvent,
// reference to the viewer DOM mounting point, useful for inserting a picker and positioning relatively inside of
viewerElement,
// you can use callback(hotspot) to emit a regular clicked/pressed/contextmenu event with a chosen hotspot
callback
) {
// Example: just always pick the first hotspot and callback to regular 'hotspot*' event behavior
callback(hotspots[0]);
// you can optionally return a clean-up function that will be called when
// a picker should be closed, so you can clean up after yourself.
// This clean-up function is called once on a subsequent pickHotspot call.
return function () {
console.log('clean up');
};
}
});
- Let CoreUIKit OfferDetails grow beyond the width of its anchor, with respect to on-screen position.
- BREAKING INCITO CHANGE Now, you need to supply the identifier of the publication rather than the Incito identifier. Plus, we've added a new event to measure how many times Incito's are opened. Anonymously.
- PagedPublicationKit: Let options be passed to Viewer when calling createViewer, like so:
bootstrapper.createViewer(data, { pageSpreadMaxZoomScale: 1 });
- Make sure PagedPublicationViewer controls are destroy()'ed properly with the viewer, event handlers and all
- Internal removal of some extraneous function binding Breaking Change: If you relied on
this
in bootstrapper.fetch() callback, it no longer refers to the bootstrapper instance.
- Fix broken PagedPublicationViewer startup
- Update dependencies, including a fix for PagedPublicationViewer multiple starts via verso-browser https://github.com/tjek/verso-browser/commit/81d95da1b1d0b26685fffd968bbbea8694252997
- Roll back to core-js 2
- Update verso-browser and incito-browser
- Fix an issue where polyfills were missing
- Introduce support for incito opened event in eventTracker
- Use new incito opened event in IncitoPublicationKit
- Add option to IncitoPublicationKit.Viewer to pass in a pagedPublicationId to be included in the incito opened event, this should be used when a user is known to already have seen the Paged Publication version of an Incito Publication.
- Use cross-fetch library for making requests in browsers and node.js
- Relaxed eventTracker requirement for PagedPublicationKit
- Updated progress indicator for IncitoPublicationKit to be more visible and more like the one in PagedPublicationKit
- Set async to true for requests
- Added ability to use EventsKit tracker in a node.js context
- Added promise return values to
SGN.CoreKit.request
andSGN.CoreKit.request
calls without callback, when supported.
- Changed the event tracker to use the new private event format. This also means you need to update your track identifier, which is now visible in the developer console on eleaflet.com/developers.
- Updated Incito library. Now, it's up to you to add event delegation to Incito rather than binding e.g.
view_clicked
to the Incito viewer. This gives you way more flexibility - Split JS and CSS into separate files for Incito Publication demo
- Removed
util.isElementInViewport
- Added
margins
parameter forutil.isElementInViewport
- Updated Incito library
- PagedPublicationKit
- Refactored
SGN.PagedPublicationKit.initialize
toSGN.PagedPublication.Bootstrapper
to split fetching and rendering of the viewer - Made hotspots into a function instead of having a setting called
showHotspots
- Refactored
- Introduced IncitoPublicationKit
- Removed unused files
- Fixed incorrect positioning of hotspots and hotspot picker in Internet Explorer
- Added CoreUIKit to core UI components such as a popover