Script

The Script resource allows the app to register custom Javascript to be run in the store or in the checkout page. Also, if the user deletes your app, then he will not have to edit his theme to remove your JavaScript. When an app is uninstalled from a store, all of the scripts the app created are automatically removed along with it.

You should have the following things into consideration:

Scripts must be served over HTTPS.
You cannot depend of any JavaScript available in the store's theme. Not even jQuery.
Another applications may be installed and can include other JavaScript in addition to yours.
When we include your script in the store, we will send a store parameter with the store id (e.g. <script type="text/javascript" src="https://myapp.com/new.js?store=1234"></script>).
Tiendanube layouts have HTML selectors designed so that applications or external agents can be anchored to the design of each store without having to adapt their code based on each layout.

Ideally, your javascript should be inside a closure to avoid any conflict:

(function () {
  // Your JavaScript
})();

Use AJAX to load specific configurations for the store. Access your own defined URL with the store ID specified in that URL. Your app will serve those store settings in JSON format, which you can then use in your JavaScript file.

If you need to use jQuery, you should request it using useJquery method. Some stores already have jQuery in their themes, and you should not assume the store has the last jQuery version.

If the store's theme includes Jquery the method will return the same version. Otherwise, it will load and returns an updated version (3.6).

useJquery is a Promise and resolves once jQuery is loaded.

useJquery().then( (jq) => {
  console.log(`I'm using jQuery version ${jq().jquery}`)
  // MyApp.init(jq); 
});

This method will ensure the jQuery existence but not the version.

Variables

We make your life easier by providing a Javascript object (called LS) with some common variables.

Store

var LS = {
    store : {
        id : /* Store's id */,
        url : /* Store's URL */
    },
    cart : {
        subtotal : /* Cart's subtotal in cents */,
        items : [
            /* For every cart item we have */
            {
                id: /* Product Variant's id */,
                name: /* Product Variant's name */,
                unit_price: /* Product Variant's price in cents */,
                quantity: /* Quantity to be purchased */,
                requires_shipping: /* True if product requires physical shipping */
            }
        ],
        has_shippable_products : /* True if at least one product requires physical shipping */,
        has_non_shippable_products : /* True if at least one product doesn`t require physical shipping */
    },
    lang : /* Current language's code (e.g. pt_BR) */,
    currency : {
        code: /* Current currency in ISO 4217 format */,
        display_short: /* Currency format string when the currency is not specified.*/,
        display_long: /* Currency format string when the currency is specified.*/,
        cents_separator: /* Symbol used for separating cents */,
        thousands_separator: /* Symbol used for separating thousands (could be blank) */
    },
    country : /* Current currency in ISO 3166-1 format */,
    customer : /* Current customer id or null if there is no logged-in customer */,
    theme : {
        code: /* Current theme's code */,
        name: /* Current theme's name */
    }
}

Product

If we are on a Product page we add:

LS.product = {
    id : /* Product's id */,
    name : /* Product's name */,
    tags : /* Array of product's tags */,
    requires_shipping : /* True if product requires physical shipping */
};
LS.variants = /* JSON encoded representation of the product variants */;

Checkout

The checkout's LS object has only some of the properties:

var LS = {
    store : {
        id : /* Store's id */,
        url : /* Store's URL */
    },
    cart : {
        subtotal : /* Cart's subtotal in cents */,
        items : [
            /* For every cart item we have */
            {
                id: /* Product Variant's id */,
                name: /* Product Variant's name */,
                unit_price: /* Product Variant's price in cents */,
                quantity: /* Quantity to be purchased */,


            }
        ]
    },
    customer : /* Current customer id or null if there is no logged-in customer */,
    lang : /* Current language's code (e.g. pt_BR) */,
    currency : /* Current currency in ISO 4217 format */
}

Note: You cannot access this variable from the JavaScript file where developers can create their own Payment Options.

Thank you page

If we are on the thank you page we add:

LS.order = {
    id : /* Order's id */,
    number : /* Order's number */,
    hash : /* Order's hash */,
    created_at : /* Order's creation date */,
    coupon : /* Array of coupon codes that apply to this order */,
    discount : /* Order's discount in cents */,
    total : /* Order's total in cents */,
    total_in_usd : /* Order's total in USD in cents */,
    gateway : /* Payment Gateway's code */
};

Properties

Property	Explanation
id	The unique numeric identifier for the Script
src	Specifies the location of the Script. Must be HTTPS.
event	DOM event which triggers the loading of the script. Valid values are onfirstinteraction (default) or onload
where	A comma-separated list of places where the javascript will run. Valid values are store (default) or checkout
created_at	Date when the Script was created in ISO 8601 format
updated_at	Date when the Script was last updated in ISO 8601 format

Available events

To prevent performance issues, we use two different events where it's possible to attach the script, onfirstinteraction, and onload.

onfirstinteraction: The scripts will be loaded and executed after the user's first interaction. A scroll up/down, a mouseclick, or a tap will trigger the event.

This event is intended for functionalities that don't affect the above-the-fold or provide other functionalities that are not needed as soon as possible.

This type of event should be the first choice for most applications.

Some application examples could be chatbots, subscription popups, product wishlists, etc.

onload: The script will be part of the critical path and will be executed as soon as possible on the page load. Its behavior is equivalent to the window.onload event.

In most cases this event should be avoided, unless you need to change some critical components above the fold or collect user-related data like behavior or conversions.

Important: For the use of onload event, it's necessary to previously request approval from api@nuvemshop.com.br. In this email you must send the functionality of the script and why it should be executed onload. Please include the APP_ID and the APP_NAME in the email title. If not approved, the script will be created with the onfirstinteraction event.

Endpoints

GET /scripts

Receive a list of all Scripts.

Parameter	Explanation
since_id	Restrict results to after the specified ID
src	Show Scripts with a given URL
created_at_min	Show Scripts created after date (ISO 8601 format)
created_at_max	Show Scripts created before date (ISO 8601 format)
updated_at_min	Show Scripts last updated after date (ISO 8601 format)
updated_at_max	Show Scripts last updated before date (ISO 8601 format)
page	Page to show
per_page	Amount of results
fields	Comma-separated list of fields to include in the response

GET /scripts

HTTP/1.1 200 OK

[
  {
    "created_at": "2013-01-03T09:11:51-03:00",
    "event": "onfirstinteraction",
    "id": 101,
    "src": "https://myapp.com/foo.js",
    "updated_at": "2013-03-11T09:14:11-03:00",
    "where": "store,checkout"
  },
  {
    "created_at": "2013-04-07T09:11:51-03:00",
    "event": "onfirstinteraction",
    "id": 5123,
    "src": "https://myapp.com/bar.js",
    "updated_at": "2013-04-08T11:11:51-03:00",
    "where": "store"
  },
  {
    "created_at": "2013-04-08T12:09:48-03:00",
    "event": "onfirstinteraction",
    "id": 6412,
    "src": "https://myapp.com/yet_another_script.js",
    "updated_at": "2013-04-08T11:11:53-03:00",
    "where": "checkout"
  }
]

GET /scripts?since_id=1234

HTTP/1.1 200 OK

[
  {
    "created_at": "2013-04-07T09:11:51-03:00",
    "event": "onfirstinteraction",
    "id": 5123,
    "src": "https://myapp.com/foo.js",
    "updated_at": "2013-04-08T11:11:51-03:00",
    "where": "store"
  },
  {
    "created_at": "2013-04-08T12:09:48-03:00",
    "event": "onfirstinteraction",
    "id": 6412,
    "src": "https://myapp.com/bar.js",
    "updated_at": "2013-04-08T11:11:53-03:00",
    "where": "checkout"
  }
]

GET /scripts/{id}

Receive a single Script

Parameter	Explanation
fields	Comma-separated list of fields to include in the response

GET /scripts/1234

HTTP/1.1 200 OK

{
  "created_at": "2013-01-03T09:11:51-03:00",
  "event": "onfirstinteraction",
  "id": 101,
  "src": "https://myapp.com/foo.js",
  "updated_at": "2013-03-11T09:14:11-03:00",
  "where": "store,checkout"
}

POST /scripts

Create a new Script.

POST /scripts

{
  "invalid_name": "foobar",
  "where": "invalid_where"
}

HTTP/1.1 422 Unprocessable Entity

{
  "event": ["can't be blank"],
  "src": ["can't be blank"],
  "where": ["is not included in the list"]
}

POST /scripts

{
  "src": "https://myapp.com/new.js",
  "event": "onfirstinteraction",
  "where": "store"
}

HTTP/1.1 201 Created

{
  "created_at": "2013-06-01T15:12:15-03:00",
  "event": "onfirstinteraction",
  "id": 8901,
  "src": "https://myapp.com/new.js",
  "updated_at": "2013-06-01T15:12:15-03:00",
  "where": "store"
}

PUT /scripts/{id}

Modify an existing Script

PUT /scripts/5123

{
  "created_at": "2013-04-07T09:11:51-03:00",
  "event": "onfirstinteraction",
  "id": 5123,
  "src": "https://myapp.com/another_bar.js",
  "updated_at": "2013-06-01T12:05:34-03:00",
  "where": "store"
}

HTTP/1.1 200 OK

{
  "created_at": "2013-04-07T09:11:51-03:00",
  "event": "onfirstinteraction",
  "id": 5123,
  "src": "https://myapp.com/another_bar.js",
  "updated_at": "2013-06-01T12:11:14-03:00",
  "where": "store"
}

DELETE /scripts/{id}

Remove a Script

DELETE /scripts/5123

HTTP/1.1 200 OK

{}

Script

Variables​

Store​

Product​

Category​

Checkout​

Thank you page​

Properties​

Available events​

Endpoints​

GET /scripts​

GET /scripts​

GET /scripts?since_id=1234​

GET /scripts/{id}​

GET /scripts/1234​

POST /scripts​

POST /scripts​

POST /scripts​

PUT /scripts/{id}​

PUT /scripts/5123​

DELETE /scripts/{id}​

DELETE /scripts/5123​

Variables

Store

Product

Category

Checkout

Thank you page

Properties

Available events

Endpoints

GET /scripts

GET /scripts

GET /scripts?since_id=1234

GET /scripts/{id}

GET /scripts/1234

POST /scripts

POST /scripts

POST /scripts

PUT /scripts/{id}

PUT /scripts/5123

DELETE /scripts/{id}

DELETE /scripts/5123