Introduction

API Key

Strap Finder API requires a unique apiKey. If we did not provide you with your apiKey, please contact us.

Strap/Watch Id

A strapId/watchId represents a unique reference for a strap/watch. The strapId/watchId is used to load a specific watch/strap. Two straps/watches of the same model, but with different colors, materials or sizes, must have two distinct strap/watch ids.

Caching

Never use server cache for Strap Finder Virtual Try-On. Strap Finder files (sf-api.js) must not be cached on your server in order to work properly.

Responsive Design

Strap Finder widgets automatically adapt their sizes to fit the html element container dimensions. This allows to support responsive layouts for different screens or devices. In order to behave correctly it is recommended to use a container with a minimal size of 300px width and 300px height.

Integration Examples

Various integration examples can be found on CodePen.

StrapFinder API

Strap Finder provides a JavaScript API for interaction. The API is your interface to the Strap Finder SDK. When you add a link to our sf-api.js script to your page, our API will be accessible at window.StrapFinder.

<script src="https://cdn.strap-finder.com/api/v1/sf-api.js" type="text/javascript"></script>

StrapFinder.getProducts

StrapFinder.getProducts(params, callback)

This is a function that returns an array of the strapIds and watchIds that are available to you. It returns an array of all of the products (SKUs) that are available using the provided apiKey.

Example

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f',
};

StrapFinder.getProducts(params, (data) => {
    console.log("watch ids:", data.watch_ids)
    console.log("strap ids:", data.strap_ids)
})

StrapFinder.createWidget

StrapFinder.createWidget(containerId, params, callback)

This method allows you to add a StrapFinder widget in the specified html element. It returns the instance of the created StrapFinder. The instance will be used to call functions.

The StrapFinder.createWidget() function is called with three arguments:

The containerId of the HTML element where the iFrame will be embedded
A params object for configuring the Strap Finder
A callback function to be executed when the Strap Finder is ready

containerId (string)

The containerId is the id of the HTML element that will embed the Strap Finder. The id must be used only once per page. If there are multiple identical ids in the page, Strap Finder will be embedded in the first element in the DOM. This parameter is mandatory.

params (object key/value)

The params object passed to createWidget() can include numerous configuration options. Here is the list of possible options:

argument	required	type	notes	example
apiKey	true	string	apiKey value	apiKey: ‘b7a9556d6d91319018315734b2cf490f’
lang	false	string	Language code value. If no value is provided, lang of the user’s browser will be used.	lang: ‘de’
css	false	string	Stylesheet to load and apply for customization. It can also be used with inline css.	css: ‘https://my-domain.com/sf-custom.css‘ css: ‘body {font-family: verdana !important;}’
mode	false	integer	Sets the Strap Finder display mode. 0 : Single Strap with User Upload of a Watch (default) 1: Strap Options for a Predefined Watch 2: Watch and Strap Portfolio	mode: 1
popupIntegration	false	object key/value	The position and size of the popup are customizable with the follwoing arguments: horizontal: ‘left’ \| ‘right’ OR centeredHorizontal: true vertical: ‘top’ \| ‘bottom’ OR centeredVertical: true width: ‘700px’ height: ‘600px’ If the size of the screen is smaller than the requested width / height, the popup will be displayed fullscreen with the close button centred on top. The popupIntegration is fully compatible with mobile integration.	popupIntegration : { centeredHorizontal: true, centeredVertical: true, width: “780px”, height: “560px” } popupIntegration: { vertical: ‘top’, horizontal: ‘left’ }
startScale	false	float	Initial scale of the displayed view.	startScale: 1.2
watchDisplay	false	string	Sets the display mode as carousel for watches in mode 2.	watchDisplay: ‘carousel’
–
onSnapshot	false	function	Triggered when a snapshot of the Strap Finder is taken.	onSnapshot: onSnapshot
onClickStrapTitle	false	function	Triggered when the user clicks on a strap title.	onClickStrapTitle: onClickStrapTitle
onClickWatchTitle	false	function	Triggered when the user clicks on a watch title.	onClickWatchTitle: onClickWatchTitle

callback (function)

The function is called when widget creation is complete. Functions on strapFinderInstance must be called only after this has been called.

Example

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f',
};

var strapFinderInstance = StrapFinder.createWidget(
    "my-sf-container",
    params,
    function () {
        console.log("strapFinderInstance is now ready!");
    }
)

Strap Finder Instance Functions

The following are some of the provided functions:

addCss(css)

Add custom CSS to the Strap Finder.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, onStrapFinderReady);
 
functiononStrapFinderReady() {
    strapFinderInstance.addCss(":root {--bg-color: #666 !important; --bg-color-sidebar: #ccc !important; --bg-color-sidebar-inner: #fff !important;} body {font-family: verdana !important;}")
}

setLang(lang)

This method allows the widget language to change dynamically. Default language is the browser’s language.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, onStrapFinderReady);
 
functiononStrapFinderReady() {
    strapFinderInstance.setLang('de');
}

reinitialize()

Reinitialize the Strap Finder.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};

strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, function() {
    strapFinderInstance.setStrap('1');
});

functionreinitialize() {
    strapFinderInstance.reinitialize()
}

getSnapshot()

Get a snapshot of the current Strap Finder display. The base 64 image is returned in the onSnapshot function given in the parameters of the createWidget function.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f',
    onSnapshot: onSnapshot,
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, function() {
    strapFinderInstance.setStrap('1');
});
 
functiononSnapshot(dataB64) {
    var img = document.getElementById("my-snapshot");
    img.src = data.dataURL;
}
 
functiongetSnapshot() {
   strapFinderInstance.getSnapshot();
}

remove(onRemoved)

Remove the Strap Finder from the parent html element.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params);

// call this function when you want to destroy the StrapFinder instance  functionremoveFromPage() {
    // remove the StrapFinder from the page after its creation
    strapFinderInstance.remove(function() {
        // called when instance is removed successfully
    });
}

setZoomFactor(factor)

Zoom the current view to the given factor.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params);
 
functionzoom(factor) {
    strapFinderInstance.setZoomFactor(factor)
}

pan(panX, panY)

Pan the view by the given X and Y values.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params);
 
functionpan(panX, panY) {
    strapFinderInstance.pan(panX, panY)
}

resetView()

Resets the view, i.e. sets pan and zoom to initial values.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params);
 
functionresetView() {
    strapFinderInstance.resetView()
}

setStrap(id)

Set the displayed strap using its ID.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params);
 
functiononStrapFinderReady() {
    strapFinderInstance.setStrap('1');
}

setWatch(id)

Set the displayed watch using its ID.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params,);
 
functiononStrapFinderReady() {
    strapFinderInstance.setWatch('1');
}

clearWatch()

Clear the currently displayed watch.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, function() {
    strapFinderInstance.setWatch('1');
});
 
functionclearWatch() {
    strapFinderInstance.clearWatch()
}

clearStrap()

Clear the currently displayed strap.

var params = {
    apiKey: 'b7a9556d6d91319018315734b2cf490f'
};
 
strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, function() {
    strapFinderInstance.setStrap('1');
});

functionclearStrap() {
    strapFinderInstance.clearStrap()
}

popupShow()

var params = {
  apiKey: "b7a9556d6d91319018315734b2cf490f",
  popupIntegration: {
    centeredHorizontal: true,
    centeredVertical: true,
    width: "600px",
    height: "800px"
  }
};

strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, function() {
    strapFinderInstance.setStrap('1');
});

functionpopupShow() {
    strapFinderInstance.popupShow();
}

popupHide()

var params = {
  apiKey: "b7a9556d6d91319018315734b2cf490f",
  popupIntegration: {
    centeredHorizontal: true,
    centeredVertical: true,
    width: "600px",
    height: "800px"
  }
};

strapFinderInstance = StrapFinder.createWidget('my-sf-container', params, function() {
    strapFinderInstance.setStrap('1');
});

window.onload = () => {
  strapFinderInstance.popupShow();
};

functionpopupHide() {
    strapFinderInstance.popupShow();
}

Documentation

Introduction

API Key

Strap/Watch Id

Caching

Responsive Design

Integration Examples

StrapFinder API

StrapFinder.getProducts

Example

StrapFinder.createWidget

containerId (string)

params (object key/value)

callback (function)

Example

Strap Finder Instance Functions

addCss(css)

setLang(lang)

reinitialize()

getSnapshot()

remove(onRemoved)

setZoomFactor(factor)

pan(panX, panY)

resetView()

setStrap(id)

setWatch(id)

clearWatch()

clearStrap()

popupShow()

popupHide()