Introduction
Swym JS loads asynchronously to ensure it does not fall in site's critical loading path. To ensure all calls to Swym APIs are made only once Swym is loaded and ready, please wrap all calls to the API in a construct as shown on the right.
function swymCallbackFn(){
// your API calls go here
}
if(!window.SwymCallbacks){
window.SwymCallbacks = [];
}
window.SwymCallbacks.push(swymCallbackFn);
This document lists and explains various front-end javascript APIs exposed by Swym. One can refer this documentation to get the formal knowledge on how to manipulate front-end behaviour of Swym’s applications according to the respective needs. In case of any incorrect or incomplete information, please reach out to the developers’ team at Swym.
In this documentation, we have covered following topics for an individual API:
- What does a particular API do?
- When it should be called?
- What are the arguments?
- Example request and response
Errors
Ideally there should not be any error while calling these APIs. In case if you encounter any such interruptions in the flow, please check the console of your web page and see if the error is coming from our end. Our Javascript APIs will leave a handy error message on the developer console if the error is caught at our level.
If you do see an error that isn't self-explanatory, please reach out to our developers’ team. In any case, we are monitoring our APIs. So, if any exceptions or errors are generated, we can check the logs and fix it for you even before you encounter them.
For the errors coming from the server, the Swym JS APIs use the following error codes :
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- You are not allowed to request this data. |
404 | Not Found -- The specified requested data could not be found. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're raising too many requests! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Wishlist button
Add to wishlist - addToWishList
_swat.addToWishList(eventObject, callbackFn, noShowNotificationopt)
window._swat.addToWishList(
{
"epi": 123,
"du": "https://yourstore.com/products/your-awesome-product",
"empi": 1234,
"iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
"pr": 50,
"stk": 100,
"variants": [{"Blue / XL": 123}]
},
function(r) {
console.log('Added to wishlist');
}
);
// An example with cprops and hashtags
window._swat.addToWishList(
{
"epi": 456,
"du": "https://yourstore.com/products/your-another-awesome-product",
"empi": 6789,
"iu" : "//www.understandfrance.org/Images/AsterixObelix2.jpg",
"pr": 70,
"stk": 10,
"variants": [{"Yellow / XL": 123}],
"cprops": {personalised: true},
"hashtags": ["summer dresses", "party wear"]
},
function(r) {
console.log('Added to wishlist');
}
);
Adds a new wishlist event. Please refer to the example. You can call this method once the window._swat object is initialized. This API operates at the epi, i.e. product variant level as set by the store.
This API can be called in the below scenarios,
- 'onclick' button on a product page
- 'onclick' button on a product quick view
- 'onclick' buttons on a collections page with multiple products
- 'onclick' buttons on a widget of multiple products, Eg: related products, top wishlist products, etc.
Tip - Before showing a button for 'Add to Wishlist', it is best to first check if the product or variant is already in the wishlist, by using the "fetch" API.
Please refer our blog/guide for directly connecting button to wishlist actions here - Wishlist Plus Customization Cheatsheet
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
empi | int/string | External product master id (if there is a group product id with different variant ids) |
iu | string | Image-uri - Without protocol so protocol can be decided while rendering to http or https |
pr | float | Price |
cpropsoptional | object | data object that can be used to pass any custom data about the event |
hashtagsoptional | array | array of wishlist collections to which this product needs to be added |
For response | function | A callback function, which takes a single argument (JSON response from the swym service) |
noShowNotification | boolean | Boolean for should the slide-out notification be shown. By default, this argument is false and the notification is shown |
In the example, the request adds the product variant to the wishlist. Please note that the these parameters are mandatory ones (epi, empi, du and iu).
Remove from wishlist - removeFromWishList
_swat.removeFromWishList(eventObject, callbackFn)
Removes a previously added wishlist event. Please refer to the example. You can call this method once the window._swat
object is initialized. This API can be used for the same scenarios as addToWishList
.
window._swat.removeFromWishList(
{
"epi": 123,
"du": "https://yourstore.com/products/your-awesome-product",
"empi": 1234,
"iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
"pr": 50,
"stk": 100,
"variants": [{"Blue / XL": 123}]
},
function(r) {
console.log('Removed to wishlist');
}
);
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
empi | int/string | External product master id (if there is a group product id with different variant ids) |
iu | string | Image-uri - Without protocol so protocol can be decided while rendering to http or https |
pr | float | Price |
For response | function | A callback function, which takes a single argument (JSON response from the swym service) |
In the example, removeFromWishList removes a previously added entry from the wish list.
Get all tracked products - fetch
_swat.fetch(callbackFn)
Example request
window._swat.fetch( function(r) {
console.log(r);
document.getElementById('demo').innerHTML = r;
});
Example response
[
{
"di": "deviceid",
"_id": "deviceid.ts",
"date": "2017-01-16",
"pt": "Your Awesome Product",
"rc": "default",
"variants": "[{\"Blue\":123}]",
"dt": "Your Awesome Product - Blue",
"et": 1,
"raw-du": "https://yourstore/products/your-awesome-product?v=123",
"act": true,
"empi": 1234,
"ts": 1111,
"du": "https://yourstore/products/your-awesome-product?v=123",
"pid": "yourstorepid",
"epi": 123,
"iu": "//yourstore.com/images/your-awesome-product-123",
"dcat1": "Personal computer",
"pr": 50,
"ct": "Accessories",
"dcat": "Mac",
"type": "product-variant"
},
{
"di": "deviceid",
"_id": "deviceid.ts",
"date": "2017-01-16",
"pt": "Your Awesome Product",
"rc": "default",
"variants": "[{\"Red\":134}]",
"dt": "Your Awesome Product - Red",
"et": 4,
"raw-du": "https://yourstore/products/your-awesome-product?v=134",
"act": true,
"empi": 1234,
"ts": 11,
"du": "https://yourstore/products/your-awesome-product?v=134",
"pid": "yourstorepid",
"epi": 134,
"iu": "//yourstore.com/images/your-awesome-product-134",
"dcat1": "Personal computer",
"pr": 45,
"ct": "Accessories",
"dcat": "Mac",
"type": "product-variant"
}
]
Fetch the history of events from the swym service. The set of events fetched from the swym service is sorted by date (reverse chronological). You can call this method once the window._swat
object is initialized.
Argument | Type | Description |
---|---|---|
callbackFn | function | A callback function with a single argument, which is a JSON response on success. |
Initialize custom button - initializeActionButtons
Let's say we have a custom button which should act as a wishlist button for a retailer. In this case, we need to add data-swaction='addToWishlist'
or data-swaction='addToWatchlist'
(depending on which app it is) attribute to that particular custom button HTML element on the retailer's store. We can use any custom selector as well if we don't want to use the data-swaction
. Now, during run-time, all such buttons will be checked and initialized by Swym. In order to do that, we have to call this API: initializeActionButtons
.
window._swat.initializeActionButtons('.product-grid', '[my-custom-wishlist-btn]');
Argument | Type | Description |
---|---|---|
containerSelector | string | A container selector which is parent of all such custom wishlist buttons |
selectoroptional | string | A selector for custom wishlist button, by default it is data-swaction |
Trigger variant change - triggerSwymVariantEvent
In Shopify, each product has multiple variants. In many stores, it is very important to capture events at a variant level, such as the variant id, variant price, variant stock, variant options, variant image, etc. The end user interacts with the product from the product details page, a collections page, a quick view popup or a widget of products. Swym provides support for managing events at product and variant levels for each of those scenarios. Find the detailed explanation below:
For a product details page - Let’s take the “onload” and “afterload” scenarios and break it down to use cases -
“onload” - When a product page is opened, following are the usual patterns,
- First variant is picked
- First variant that is in stock and available to purchase is picked
- The variant specified in the query parameter
variant=<
to the url is picked>
For most themes, scenarios 1 and 3 are common, but there are no defined rules. Also, it can be the theme developer’s choice as how to control product details page. Swym has inbuilt support for scenarios 1 and 3. For ensuring scenario 2, the below snippet needs to be called to let Swym know of the current variant, once window._swat
is initialized.
“afterload” - After page is opened, user can switch variants. Most themes use Shopify’s Shopify.OptionSelector
library to enable variant selection elegantly. Swym has inbuilt support for this plugin. However there are no defined rules for this and hence in cases where the implementation is different, the below snippet needs to be called to let Swym know of the current variant whenever it is changed.
Wishlist count
Get user's wishlist count - wishlistCount
_swat.wishlistCount(callbackFn)
Get the current count of wishlist.
window._swat.wishlistCount(
function(r) {
console.log('Wishlist items - ', r);
}
);
Argument | Type | Description |
---|---|---|
callbackFn | function | A callback function which receives a single argument, which is the number of wishlist items for the user |
Render user's wishlist count - renderWishlistCount
_swat.renderWishlistCount(anchorDomElem, callbackFn, timeoutopt)
In order to render the number of wishlisted items (generally on swym's anchor/launcher) use this API. We can also attach it to custom element. Manual style modification might be needed in that case.
window._swat.renderWishlistCount(anchorElem.querySelector('.swym-anchor-badge'), function(cnt, elem){
console.log("renderWishlistCount was called", cnt, elem);
}, 1500);
Argument | Type | Description |
---|---|---|
elem | DOM element | A DOM element to update the badge on |
callbackoptional | function | A callback function with an object that gives event after default actions |
timeoutoptional | integer | Miliseconds after which you want to update the render count on screen |
Custom wishlist page
Get all tracked products
Same as fetch.
Get products by event type - fetchWrtEventTypeET
_swat.fetchWrtEventTypeET(callbackFn, eventType)
Fetch the items based on a filter from the swym service. The set of events fetched from the swym service is sorted by date (reverse chronological). You can call this method once the window._swat object is initialized. This is used to fetch wishlist items, please see the example.
Example request
window._swat.fetchWrtEventTypeET(
function(r) {
// Get wishlist items
console.log(r);
document.getElementById('demo').innerHTML = r;
},
window._swat.EventTypes.addToWishList
);
Example response
[
{
"di": "deviceid",
"_id": "deviceid.ts",
"date": "2017-01-16",
"pt": "Your Awesome Product",
"rc": "default",
"variants": "[{\"Blue\":123}]",
"dt": "Your Awesome Product - Blue",
"et": 4,
"raw-du": "https://yourstore/products/your-awesome-product?v=123",
"act": true,
"empi": 1234,
"ts": 1111,
"du": "https://yourstore/products/your-awesome-product?v=123",
"pid": "yourstorepid",
"epi": 123,
"iu": "//yourstore.com/images/your-awesome-product-123",
"dcat1": "Personal computer",
"pr": 50,
"ct": "Accessories",
"dcat": "Mac",
"type": "product-variant"
},
{
"di": "deviceid",
"_id": "deviceid.ts",
"date": "2017-01-16",
"pt": "Your Awesome Product",
"rc": "default",
"variants": "[{\"Red\":134}]",
"dt": "Your Awesome Product - Red",
"et": 4,
"raw-du": "https://yourstore/products/your-awesome-product?v=134",
"act": true,
"empi": 1234,
"ts": 11,
"du": "https://yourstore/products/your-awesome-product?v=134",
"pid": "yourstorepid",
"epi": 134,
"iu": "//yourstore.com/images/your-awesome-product-134",
"dcat1": "Personal computer",
"pr": 45,
"ct": "Accessories",
"dcat": "Mac",
"type": "product-variant"
}
]
Argument | Type | Description |
---|---|---|
callbackFn | function | A callback function with a single argument, which is a JSON response on success. |
event type | int | enum Reference |
Email Wishlist - sendEmailWishList
_swat.sendEmailWishList(callbackFn, toEmailId, fromName, note, hashtagopt)
Sends an email with the wishlist contents of the current user to a given email id.
window._swat.sendEmailWishList(
function(r) {
console.log('Email sent!');
},
"abc@xyz.com",
"Admin",
"Hey, check out these products!"
);
Argument | Type | Description |
---|---|---|
callbackFn | function | A callback function which takes a single argument (JSON response from the swym service) |
emailId | string | An email Id to send the favorites to |
fromEmailId | string | The sender's email id / name |
note | string | Some personal note that needs to be sent along with the email contents |
hashtagoptional | string | If collections of wishlist is used, a particular collection name that needs to be shared |
Add product to cart - replayAddToCart
_swat.replayAddToCart(productJson, variantId, callbackFn, errorFn)
From your wishlist popup or page, when you want to add a product to the cart of the store, create your add to cart button (if you are using custom button) and call this API.
window._swat.replayAddToCart(
{empi: 1234, du: "https://yourstore.com/products/your-another-awesome-product"},
67,
function() {
console.log("Successfully added product to cart.");
},
function(e) {
console.log(e);
}
);
Argument | Type | Description |
---|---|---|
product | object | An object of the product which needs to be added to cart with keys "empi" (product master id) and "du" (product url) |
epi | integer | variant id of the product which will be added to cart |
successFn | function | A function which will be called when product is successfully added to card |
errorFn | function | A function which will be called if case of any errors |
Get complete product details - getProductDetails
_swat.getProductDetails(productObject, callbackFn, errorFn)
Let's say we want entire details about a product, which includes variants, stock level etc (all such info about product), then we can use this API which will return a productJson object on successful call.
window._swat.getProductDetails(
params,
function(productJson) {
console.log("Entire product json:", productJson);
},
function(e) {
console.log(e);
}
);
Argument | Type | Description |
---|---|---|
params | object | An object with product keys epi (variant id), empi (product master id), du (product url) |
successFn | function | A function which will be called with productJson |
errorFn | function | A function which will be called if case of any errors |
Connect device to email address - remoteAuthRequest
_swat.remoteAuthRequest(callbackFn, errorFn, toEmailId)
Request the swym service to send a one time email validation link. A mail will be sent on the email address which is given as argument to this API. Upon clicking "Confirm", user will be redirected to site and authenticated.
window._swat.remoteAuthRequest(
function(resp) { console.log(resp); },
function(err) { console.log(err); },
"my.email@domain.com"
);
Argument | Type | Description |
---|---|---|
callbackFn | function | A callback function with a single argument, which is a JSON response called by remoteAuthRequest |
errorFn | function | A function which will be called in case of any errors |
email address | string | A valid email address |
Check if device has an associated email - authCheck
_swat.authCheck(callbackFn)
Example request
window._swat.authCheck(
function(r) {
console.log(r);
document.getElementById('demo').innerHTML = r;
}
);
Example response if auth
{
"email": "r@foo.com",
"authn": true
}
Example response if not auth
{
"authn": false
}
Query the swym service to see if the current browser is authenticated.
Argument | Type | Description |
---|---|---|
callbackFn | function | A callback function with a single argument, which is a JSON response called by authCheck. |
Update a wishlist event - updateWishlistEvent
_swat.updateWishlistEvent(eventsToUpdate, callbackFn, errorFn)
Allows updating "cprops" parameter for an array of events. More info on "cprops" is here.
window._swat.updateWishlistEvent(
[
{
epi: 123,
cprops: { x: 1, y: 2 }
}
],
function(r) { console.log(r) },
function(e) { console.log(e) }
);
Argument | Type | Description |
---|---|---|
eventsToUpdate | array | An array of objects containing the keys "epi" and "cprops" corresponding to the events that need to be updated |
successCallback | function | Function that gets called if the events are updated successfully |
errorCallback | function | Function that gets called if the update ran into an error |
Wiring "View your Wishlist" in notification to custom wishlist page
On adding a product to wishlist, you will see a fly-out notification. This notification has a "View your wishlist" CTA. By default, clicking on this button will either open up the Wishlist popup or redirect to the default Swym wishlist page, depending on your settings.
If you are building a custom wishlist page, you will need to -
- Set the "Display the Wishlist module as" setting to "Separate page" in the Swym Dashboard.
- Override the redirect function as shown on the right.
SwymUtils.getHostedURL = function(){
return "/pages/wishlist"; // your wishlist URL here
};
Note: As with any Swym API call, please wrap this call in the SwymCallbacks construct to ensure it gets called only once Swym is ready.
Invoking the Swym quick-view (lightweight ui) popup from anywhere
_swat.ui.openProductDetails(epi, du)
Swym ships with a quick view popup implementation that can be invoked anywhere and for any product. You might want to use it for your custom wishlist page or for a wishlist on the cart page widget to allow users to choose the variant they want to add to cart or to read more about a product they care about.
window._swat.ui.openProductDetails(
2056554534059,
"https://mystore.myshopify.com/product-url"
);
Argument | Type | Description |
---|---|---|
epi | Int | The variant id of the product needed to be shown |
uri | String | The product URL |
Back In Stock Product Alerts
Show "Email me when available" widget - addToWatchList
_swat.addToWatchList(clickEvent, eventMap, callbackFn, renderIntoNodeopt)
When a product is out of stock and you want to show "Email me when available" subscription button, we can use this API to add a product to user's "watchlist". Whenever product is back in stock, an email will be sent to user automatically if addToWatchlist
was performed for that product for user.
window._swat.addToWatchList(
clickEventObj,
{ epi: 10, empi: 10, et: 8, iu: "IMAGE_URL" }, // event type 8 stands for registering a "notify me" event.
function(r) {
console.log("response", r);
},
document.querySelector(".INJECT-FORM");
);
Argument | Type | Description |
---|---|---|
clickEvent | object | event object of click listener event |
evtMap | object | An object consisting epi, empi and iu |
callbackFn | function | A callback function which will be called on success |
renderIntoNodeoptional | DOM node | A DOM node where you want to show addToWatchlist as popup/inline form |
Request Back In Stock Product Alerts for a product - sendWatchlist
_swat.sendWatchlist(mediumValue, sendMedium, eventObject, callbackFn, errorFn, addToMailingListopt)
Sends an back-in-stock alert request to the Swym platform.
window._swat.sendWatchlist(
"demo@demo.com",
"email",
{
epi: 123,
empi: 12,
iu: "https://a.com/b.jpeg",
pr: 23
},
function(r) { console.log(r) },
function(e) { console.log(e) },
1
);
Argument | Type | Description |
---|---|---|
mediumValue | string | Value of the medium (currently supported ‘email’, hence email Id) |
medium | string | What id is collected (currently 'email' supported) |
product | object | Object with keys - {"epi" (variant id), "empi" (product master id), "iu" (image url), "pr" (price)} |
callbackFn | function | Function that gets called after a successful HTTP API call |
errorFn | function | Function that gets called when an error occurs |
addToMailingListoptional | int | Possible values: 1(opted in) or 0(opted out), to tell if user will be added to the mailing list (Note:- requires mailing list feature to be set up from Swym's end) |
Request product alerts for - product with specific topic
_swat.subscribeForProductAlert(mediumValue, medium, product, successFn, errorFn, addToMailingList, topic)
Send a product alert for a given topic. An alert email will be sent to subscriptions made using this API when given topic condition is fulfilled.
window._swat.subscribeForProductAlert(
"demo@demo.com",
"email",
{
epi: 123,
empi: 12,
iu: "https://a.com/b.jpeg",
pr: 23
},
function(response) { console.log(response) },
function(error) { console.log(error) },
0,
"comingsoon"
);
Argument | Type | Description |
---|---|---|
mediumValue | string | Value of the medium (currently supported ‘email’, hence email Id) |
medium | string | What id is collected (currently 'email' supported) |
product | object | Object with keys - {"epi" (variant id), "empi" (product master id), "iu" (image url), "pr" (price)} |
successFn | function | Function that gets called after a successful API call |
errorFn | function | Function that gets called when an error occurs |
addToMailingList | int | Possible values: 1(opted in) or 0(opted out), to tell if user will be added to the mailing list (Note:- requires mailing list feature to be set up from Swym's end) |
topic | string | topic like "comingsoon", defaults to "backinstock" if not provided |
Collections of Wishlist (Premium)
The Swym platform supports having multiple wishlists for a user, eg: my lounge, my bedroom, etc. or in case of fashion eg: my outdoor collection, my summer list, etc. These APIs are available on the premium plans, please contact us to enable these APIs for your installation.
Get products for a collection - fetchWishlistWRTHashtag
_swat.fetchWishlistWRTHashtag(callbackFn, hashtag)
window._swat.fetchWishlistWRTHashtag(function(products){
// Render products
}, "Summer Collection");
When we want to get the information about various wishlist related activities based on hashtags, we can use this API. We will get an array of products in response.
Argument | Type | Description |
---|---|---|
renderFn | function | A function to render the response product JSONs |
hashtag | string | Name of the hashtag |
Add collections to a product - addCollectionsToProduct
_swat.addCollectionsToProduct(variantId, collectionsToAdd, callbackFn, errorFn)
Add an array of collections to a product. When adding a product to wishlist, this API has to be called before calling addToWishlist API.
window._swat.addCollectionsToProduct(
epi, // epi is the currently selected variant id
["My Lounge"],
function(){
console.log("Added to collection");
}
);
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
Collections to add | array | Array of hashtags eg: ["My Lounge"] |
Success callbackoptional | function | Success callback function which will be called upon successful response. |
Error callbackoptional | function | Error callback function which will be called on unsuccessful response |
Add products to a collections - addProductsToCollection
_swat.addProductsToCollection(collection, variantIdsToAdd, callbackFn, errorFn)
Add a list of products to a collection.
window._swat.addProductsToCollection(
"My Lounge",
[ epi ], // epi is the currently selected variant id
function() {
console.log("Added to collection");
}
);
Argument | Type | Description |
---|---|---|
collection | string | e.g. “My Lounge” |
productsToAdd | array | List of variant ids to add to the collection |
Success callbackoptional | function | Success callback function which will be called upon successful response. |
Error callbackoptional | function | Error callback function which will be called on unsuccessful response |
Get all collections - getAllCollections
_swat.getAllCollections(callbackFn, bImmediateopt)
Gets all collections for the current user.
window._swat.getAllCollections(function(collections){
// code to use the returned collections
})
var collections = window._swat.getAllCollections(
function(collections){},
true
); // with the bImmediate argument
Argument | Type | Description |
---|---|---|
callback | function | A callback function that will receive all the collections |
bImmediate | boolean | Boolean for whether to get all collections from in-memory cache or make an API call. If true, the API will return results. If false, the results will be returned to the callback function. |
Remove collections from a product - removeCollectionsFromProduct
_swat.removeCollectionsFromProduct(variantId, collectionsToRemove, callbackFn, errorFn)
Remove a set of collections from a wishlisted product. Let’s say a product is added in some custom collections (product has hashtags) and we want to remove a product from some particular collections. Call this API and it will remove particular hashtags from a swym product’s data. Now, product will not be shown in those collections anymore.
window._swat.removeCollectionsFromProduct(
141445464108,
[ "summer collection", "ann's birthday" ],
function(data) {},
function(err) {}
);
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
collectionsToRemove | array | An array of collections to remove |
Success callbackoptional | function | Success callback function which will be called upon successful response. |
Error callbackoptional | function | Error callback function which will be called on unsuccessful response |
Remove products from a collection - removeProductsFromCollection
_swat.removeProductsFromCollection(collection, variantIdsToRemove, callbackFn, errorFn)
Remove an array of products from a collection.
window._swat.removeProductsFromCollection(
"summer collection",
[ 141445464108 ],
function(data) {},
function(err) {}
);
Argument | Type | Description |
---|---|---|
collection | string | Collection name |
productsToRemove | array | An array of variant ids to remove |
Success callbackoptional | function | Success callback function which will be called upon successful response. |
Error callbackoptional | function | Error callback function which will be called on unsuccessful response |
Remove a collection - removeWishlistCollection
_swat.removeWishlistCollection(collection, callbackFn, errorFn)
Removes a wishlist collection.
window._swat.removeWishlistCollection(
"Patio furniture",
function(msg) {},
function(err) {}
);
Argument | Type | Description |
---|---|---|
collectionToRemove | String | Name of the collection to remove |
Success callbackoptional | function | Success callback function which will be called upon successful response. |
Error callbackoptional | function | Error callback function which will be called on unsuccessful response |
Social sharing of Wishlist (Premium)
Share wishlist on social media - shareWishlistSocial
_swat.shareWishlistSocial(hashtag, shareUrlTemplate, platform, note, errCallBack)
This API creates the unique URL for a particular sharing platform and opens a new dialog in that platform to perform the sharing step. For eg., for facebook, the share page will be opened in a new window.
window._swat.shareWishlistSocial(
null,
"https://www.facebook.com/sharer.php?u={{shareurl}}&t={{note}}",
"facebook",
"Hello World",
function(err) { console.log(data) }
); // will open facebook share dialog
Argument | Type | Description |
---|---|---|
hashtag | string | If collections of Wishlist is not enabled, hashtag has to be set as null. |
platformShareUrlTemplate | string | The social platform-specific share URL with Mustache tags. Out of the box, platforms supported are "facebook", "twitter", "googleplus". To get share urls for these, use the variable - _swat.retailerSettings.Wishlist.SharingModes . This has the default icon url, share url and key for each of these platforms. Again, new platforms can be added here and/or default icons can be changed for you if you need it. |
platform | string | The key to one of the sharing platforms. By default, one of "facebook", "twitter", "googleplus" |
note | string | Some platforms allow to send a custom note along with shared url. This field is to capture that message. Amongst the defaults, at the moment, notes only work with twitter. |
errCallBack | function | Function that gets called if there is an error. Called with error message as argument. |
Generate shareable wishlist URL - generateSharedWishlistURL
_swat.generateSharedWishlistURL(hashtag, callbackFn, errCallBack)
A lower level API that returns the unique wishlist URL that can be shared anywhere. This URL will return the user who clicks on it back to the site into the default share wishlist page. This page can be overridden from the retailer settings if need be.
window._swat.generateSharedWishlistURL(
null,
function(data) { console.log(data); }, // returns the generated url
function(data) { console.log(data); }
);
Argument | Type | Description |
---|---|---|
hashtag | string | If collections of Wishlist is not enabled, hashtag has to be set as null . |
successFn | function | Function that gets called if the URL is generated successfully. The generated url is sent as argument to this function. |
errorFn | function | Function that gets called if the URL generation fails. Error message is passed as argument. |
Enum reference
EventType (et)
"et"
0 - Unknown,
1 - product,
2 - category,
3 - cart
4 - wishlist
5 - coupon
6 - product purchase
7 - removed from cart
Glossary
DeviceCategory (dcat)
“DeviceCategory” is an enum that will typically return one of these three types:
"Personal computer"
“Tablet”
“Smartphone”
JSON key reference for sending pageview/wishlist/cart events
Argument | Type | Description |
---|---|---|
et | int/enum | event-type (see above) |
pr | float | price |
dt | string | doc-title |
du | string | doc-uri - Full url with protocol |
iu | string | image-uri - Without protocol so protocol can be decided while rendering to http or https |
ru | string | referrer-uri |
ct | string | category-type (Example; Womens Shoes) |
bt | string | brand-type (Example: Nike) |
epi | int/string | product variant id (variant level if available) |
empi | int/string | product master id (if there is a group product id with different variant ids) |
qty | int | quantity |
pt | string | product title |
stk | int | stock value |
variants | JSON | variants (Example - [{"Black/blue": < |
cprops | object | custom parameter to add any custom data to the event. Fetch will return this data. |
Custom implementation
If you are building a custom storefront using Vue.JS / React or Angular, check out our fork from Shopify's React + GraphQL storefront example.
The first commit has all the changes necessary to get started with Swym APIs on a custom storefront on Bigcommerce / Magento or Shopify.
The APIs below document all the APIs you will need to implement the complete platform functionality into your storefront.
Track pageview - trackPageview
_swat.trackPageview(eventObject, callbackFn)
Sends a page view event , by default. Specific information regarding the page is automatically collected and sent (if unspecified and detected from the page). You can call this method once the window._swat
object is initialized.
This API can be called in below scenarios,
A product page is loaded
A product is loaded in a quick view popup
A product variant is changed, if you want more granularity in tracking, at a variant level in addition to the above two scenarios
window._swat.trackPageview({
"epi": 123,
"du": "https://www.understandfrance.org/AsterixObelix",
"empi": 1234,
"iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
"pr": 50,
"stk": 100,
"variants": [{"Blue / XL": 123}]
},
function(r) {
console.log('Reported pageview event');
});
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
empi | int/string | External product master id (if there is a group product id with different variant ids) |
iu | string | Image-uri - Without protocol so protocol can be decided while rendering to http or https |
pr | float | Price |
For response | function | A callback function, which takes a single argument (JSON response from the swym service) |
Track add to cart event - addToCart
_swat.addToCart(eventObj, callbackFn)
Adds a new cart event. Please refer to the example. You can call this method once the window._swat
object is initialized.
window._swat.addToCart(
{
"epi": 123,
"du": "https://yourstore.com/products/your-awesome-product",
"empi": 1234,
"iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
"pr": 50,
"qty": 4,
"stk": 100,
"variants": [{"Blue / XL": 123}]
},
function(r) {
console.log('Reported add to cart event');
}
);
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
empi | int/string | External product master id (if there is a group product id with different variant ids) |
iu | string | Image-uri - Without protocol so protocol can be decided while rendering to http or https |
pr | float | Price |
For response | function | A callback function, which takes a single argument (JSON response from the swym service) |
Track purchase event - reportPurchase
_swat.reportPurchase(eventObj, callbackFn)
Adds a new purchase event. Please refer to the example. You can call this method once the window._swat
object is initialized.
window._swat.reportPurchase(
{
"epi": 123,
"du": "https://yourstore.com/products/your-awesome-product",
"empi": 1234,
"iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
"pr": 50,
"qty": 4,
"stk": 96,
"variants": [{"Blue / XL": 123}]
},
function(r) {
console.log('Reported purchase');
}
);
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
empi | int/string | External product master id (if there is a group product id with different variant ids) |
iu | string | Image-uri - Without protocol so protocol can be decided while rendering to http or https |
pr | float | Price |
For response | function | A callback function, which takes a single argument (JSON response from the swym service) |
Track drop from cart event - dropFromCart
_swat.dropFromCart(eventObject, callbackFn)
Adds a new removed from cart event. Please refer to the example. You can call this method once the window._swat
object is initialized.
window._swat.dropFromCart(
{
"epi": 123,
"du": "https://yourstore.com/products/your-awesome-product",
"empi": 1234,
"iu" : "//www.understandfrance.org/Images/AsterixObelix.jpg",
"pr": 50,
"qty": 4,
"stk": 100,
"variants": [{"Blue / XL": 123}]
},
function(r) {
console.log('Reported dropped from cart');
}
);
Argument | Type | Description |
---|---|---|
epi | int/string | External product unique id (variant level if applicable) |
empi | int/string | External product master id (if there is a group product id with different variant ids) |
iu | string | Image-uri - Without protocol so protocol can be decided while rendering to http or https |
pr | float | Price |
For response | function | A callback function, which takes a single argument (JSON response from the swym service) |
REST APIs (Premium)
Intro
In addition to our JavaScript SDK, Swym APIs are also available as REST endpoints. Developers can use these endpoints to integrate functionalities of the Swym platform in mobile apps, embedded devices, third-party software etc.
Authentication
Swym REST APIs follow Basic Authentication. In the Authorization header of your request, you will need username and API key. Use your "provider id" as username. You can find your "provider id" by typing _swat.pid
in the developer console after opening your site.
For the API key, please contact our support team by raising a ticket. Since REST APIs are a Premium plan and above feature only, we provision API keys on a case by case basis. Also, the API endpoint is determined by the tier on which your store is provisioned on the Swym platform. Our support team will be able to provide you with the correct endpoint using your store details.
Fetch wishlist products for a user
curl -X GET \
'https://YOUR_SWYM_ENDPOINT/storeadmin/user/wishlist?useremail=demouser@demo.com' \
-H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
-H 'Content-Type: application/x-www-form-urlencoded'
Example response:
{
"metadata": [
{
"inactive": false,
"vendor": "Pure Fix Cycles",
"vval1": "50 cm",
"iqty": 100,
"_hv": "Oi+ZI8dGO/d6bPkDuNzX61IGrc/PQPBOq9HmMfjy9iI=",
"empi": 1483962056779,
"title": "Alfa",
"prodtype": "Fixed Gear Bicycle",
"sku": "The Alfa - Small",
"du": "https://engagedemo.myshopify.com/products/the-alfa",
"pid": "Muz0BmP2s4Nu+YhQLYhKKRqe11LtYYeC/2Ju3Z0yYqk=",
"epi": 13585114988619,
"id": "a4c07b32-cc59-4abd-807b-32cc598abd87",
"iu": "https://cdn.shopify.com/s/files/1/2241/2845/products/ALFA_SIDE_WEB.jpg?v=1542443636",
"uri": "http://engagedemo.myshopify.com/products/the-alfa?variant=13585114988619",
"pr": 1981.77,
"vkey1": "Size"
}
],
"epis": [
{
"epi": 13585114988619,
"ts": 1561451272218,
"_id": "8c09ffe4-1262-4b6d-b203-98bd0ac593af.1561451272218",
"date": "2019-06-25",
"dcat": "Mac",
"dcat1": "Personal computer",
"di": "8c09ffe4-1262-4b6d-b203-98bd0ac593af",
"et": 4
}
]
}
Example call with "cached-products" parameter:
curl -g -X GET \
'https://YOUR_SWYM_ENDPOINT/storeadmin/user/wishlist?useremail=demouser@demo.com&cached-products=[{%22epi%22:%2013585114988619,%20%22_hv%22:%20%22Oi%2BZI8dGO%2Fd6bPkDuNzX61IGrc%2FPQPBOq9HmMfjy9iI%3D%22}]' \
-H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
-H 'Content-Type: application/x-www-form-urlencoded'
With this API, you can fetch all the wishlisted products for a shopper given email address.
The response here contains two important keys - metadata
and epis
. The epis
key contains data about the wishlist event (when it happened, device info, etc) while the metadata
key contains data about the product for which the event happened. While rendering with this data, loop over the epis
key, take the epi (variant id) and merge it with its corresponding object in the metadata
key (using the epi
key in each object inside metadata
key). This will give you a list that has complete data about a wishlist event.
To optimise data sent over the wire, this API also provides a "cached-products" parameter. This parameter determines the client's product metadata state. If the client already has the latest metadata about a product, it's not sent again for that product. Whenever metadata about a product is sent by a Swym API, "_hv" key is returned along with it. This key is the "freshness stamp" for a product. While making the next request, if the client sends the "cached-product" parameter with the variant id and the stamp for the product's metadata that the client has, Swym checks if the stamp represents the most recent state. If it does, Swym API will not return the product metadata again.
Field | Type | Description |
---|---|---|
useremail | string | The customer's email address |
cached-products optional | Array[object] | Array of json objects containing the variant id and hash value of product data available to the client |
Add products to user's wishlist
curl -X POST \
'http://YOUR_SWYM_ENDPOINT/storeadmin/user/add-wishlist?useremail=demouser@demo.com' \
-H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d epis=%5B13585100865611%5D
Example response:
{"message":"Product(s) added to user collection"}
Using this API, you can add an array of products to a user's wishlist, given their email address.
Query Parameters
Field | Type | Description |
---|---|---|
useremail | string | The customer's email address |
appId optional | string | the type of client making this request. Defaults to "StoreadminApi". Can be "mobileApp" if app is making the request. |
Request Body
Field | Type | Description |
---|---|---|
epis | Array[object] | Array of variant ids of the products to be added to wishlist. |
Subscribe to Back In Stock Product Alerts on a product
Using this API, you can subscribe users to Back In Stock Product Alerts on products when they are currently out of stock. Please note, this only works if your inventory is managed by your e-commerce platform i.e. Shopify, Bigcommerce or Magento. You will also have to ensure on your end that the user is only able to subscribe to alerts on a product that's out of stock.
curl -X POST \
'http://YOUR_SWYM_ENDPOINT/storeadmin/user/subscribe-isa?useremail=demouser@demo.com' \
-H 'Authorization: Basic BASE64-ENCODING-OF-"username:password"' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d epis=%5B13585100865611%5D
Example response:
{"message":"Product(s) added to user collection"}
Query Parameters
Field | Type | Description |
---|---|---|
useremail | string | The customer's email address |
Request Body
Field | Type | Description |
---|---|---|
epis | Array[object] | Array of variant ids of the products for which the user needs to be subscribed for alerts. |