Difference between revisions of "API ScriptTag"

From Spiffy Stores Knowledge Base

m
 
Line 1: Line 1:
The ScriptTag resource represents remote JavaScripts which are loaded into the pages of a store's shopfront and in the order status page of checkout. This makes it easy to add functionality to those pages without touching any theme templates.
+
The ScriptTag resource represents remote JavaScript code that is loaded into the pages of a store's shopfront or the checkout pages. This lets you add functionality to these pages without needing to update any theme templates.
  
A script tag has the following attributes:
+
Script tags are scoped to the app that created them. When an app is uninstalled from a store, all of the script tags associated with it are automatically removed.
  
* src: The URL of the remote script.
+
== ScriptTag Properties ==
* event: The DOM event which triggers the loading of the script. Currently, "onload" is the only supported event.
 
* display_scope: Tell Spiffy Stores where to include the script; "online_store", "order_status" or "all". Default to "all".
 
  
 +
{| class="reference"
 +
!id
 +
|<pre>{ "id" : 191 }</pre>
 +
A unique numeric identifier for the script tag.
 +
|-
 +
!src
 +
|<pre>{ "src" : "https://js-library.com/widget.js" }</pre>
 +
The URL of the remote script that is to be included on the page.
 +
|-
 +
!event
 +
|<pre>{ "event": "onload" }</pre>
 +
The DOM event that triggers the loading of the script. Valid values are:
  
ScriptTags are scoped to the app that created them. When an app is uninstalled from a shop, all of the script tags which it created are automatically removed along with it.
+
* onload
 
+
|-
 
+
!display_scope
==What you can do with ScriptTag==
+
|<pre>{ "display_scope": "online_store" }</pre>
 
+
The page or pages where the script should be included. Valid values are:
The Spiffy Stores API lets you do the following with the ScriptTag resource. More detailed versions of these general actions may be available:
 
 
 
* GET /admin/script_tags.json<br>Receive a list of all ScriptTags
 
* GET /admin/script_tags/count.json<br>Receive a count of all ScriptTags
 
* GET /admin/script_tags/#{id}.json<br>Receive a single ScriptTag
 
* POST /admin/script_tags.json<br>Create a new ScriptTag
 
* PUT /admin/script_tags/#{id}.json<br>Modify an existing ScriptTag
 
* DELETE /admin/script_tags/#{id}.json<br>Remove a ScriptTag from the database
 
 
 
 
 
==ScriptTag properties==
 
  
<html>
+
* online_store: Include the script only on the shopfront pages
  <style type="text/css">
+
* order_checkout: Include the script on the checkout pages
  table.wikitable td { padding: 10px 20px !important; text-align: left; vertical-align: top; }
+
* all: Include the script on all pages.
  table.wikitable pre {padding: 0 !important; border: none !important; }
 
  </style>
 
</html>
 
{| class="wikitable" style="width: 100%"
 
|style="width: 30%"|created_at
 
|<pre>"created_at": "2012-08-24T14:01:47-04:00"</pre><br>The date and time when the ScriptTag was created. The API returns this value in ISO 8601 format.
 
|-
 
|event
 
|<pre>"event": "onload"</pre><br>DOM event which triggers the loading of the script. Valid values are: "onload."
 
|-
 
|id
 
|<pre>"id": 596726825</pre><br>The unique numeric identifier for the ScriptTag.
 
 
|-
 
|-
|src
+
!created_at
|<pre>"src": "https://js-aplenty.com/foo.js"</pre><br>Specifies the location of the ScriptTag.
+
|<pre>{ "created_at": "2008-07-15T20:00:00-04:00" }</pre>
 +
The date and time (ISO 8601 format) when the script tag was created.
 
|-
 
|-
|display_scope
+
!updated_at
|<pre>"display_scope": "online_store"</pre><br>Specifies where the file should be included. "online_store" means only web storefront, "order_status" means only the order status page, while "all" means both.
+
|<pre>{ "updated_at": "2008-07-16T20:00:00-04:00" }</pre>
|-
+
The date and time (ISO 8601 format) when the script tag was last updated.
|updated_at
 
|<pre>"updated_at": "2012-08-24T14:01:47-04:00"</pre><br>The date and time when the ScriptTag was last updated. The API returns this value in ISO 8601 format.
 
 
|}
 
|}
  
 +
== Endpoints ==
  
== Endpoints==
+
=== <code>GET /api/script_tags.json</code> ===
<html>
 
<style type="text/css">
 
  
.api-endpoint-request {
+
Retrieve a list of all script tags.
  padding: 15px 30px;
 
  display: block;
 
  background: #30373b;
 
  color: #fff;
 
}
 
  
.api-endpoint-request-type {
+
==== Optional Parameters ====
  display: block;
 
  float: left;
 
  background: #2a2c2e;
 
  padding: 15px 30px;
 
  margin: -15px 30px 0 -30px;
 
  color: #fff;
 
}
 
  
.api-endpoint-description {
+
{| class="reference"
  padding: 15px 30px;
+
!limit
  display: block;
+
|Number of results returned. The default is 30, with a maximum of 50 in a single request.
  background: #f9fafa;
 
  border-bottom: 0;
 
}
 
 
 
.api-endpoint-content, .api-endpoint-description {
 
  border: 1px solid #e5e5e5;
 
  border-top: 0;
 
}
 
 
 
.api-endpoint-queryparameters {
 
  border-top: 1px solid #e5e5e5;
 
}
 
 
 
.api-endpoint-queryparameters table {
 
  border-left: 0;
 
  border-top: 0;
 
  margin-top: 0;
 
}
 
 
 
.api-endpoint-queryparameters table td, .article table th, .toggleBox table td, .toggleBox table th, .toc table td, .toc table th, .videos-page .section-heading table td, .videos-page .section-heading table th {
 
  padding: 15px;
 
  border-right: 1px solid #e5e5e5;
 
  border-bottom: 1px solid #e5e5e5;
 
  vertical-align: top;
 
}
 
 
 
.h3 {
 
  font-weight: 500;
 
  -webkit-font-smoothing: antialiased;
 
  display: block;
 
  margin-bottom: 0.55em;
 
  margin-top: 0.55em;
 
  color: #30373b;
 
  font-size: 1.25em;
 
  line-height: 1.5;
 
}
 
 
 
.h4 {
 
  font-weight: 500;
 
  -webkit-font-smoothing: antialiased;
 
  display: block;
 
  color: #30373b;
 
  font-size: 1.125em;
 
  line-height: 1.5;
 
  margin-bottom: -1em;
 
}
 
 
 
.plain, code {
 
  background-color: rgba(0, 0, 0, 0);
 
  border: none;
 
  padding: 0 !important;
 
  font-size: 1.3em;
 
}
 
</style>
 
</html>
 
 
 
<span class="api-endpoint-request"><span class="api-endpoint-request-type api-endpoint-request-type-get">GET</span> /admin/script_tags.json </span>
 
 
 
{| class="wikitable" style="width: 100%"
 
|style="width: 30%"|limit
 
|<p>Amount of results</p>(default: 50) (maximum: 250)
 
 
|-
 
|-
|page
+
!page
|Page to show (default: 1)
+
|The number of the page to return. The number of results per page is set by the <code>limit</code> parameter. If more results are required, then submit the request again, increasing the page number each time.
 
|-
 
|-
|since_id
+
!since_id
|Restrict results to after the specified ID
+
|Limit the results to only include objects which have an id greater than the given value.
 
|-
 
|-
|created_at_min
+
!src
|Show script_tags created after date (format: 2014-04-25T16:15:47-04:00)
+
|Limit the results to only include script tags with the given source URL.
 
|-
 
|-
|created_at_max
+
!created_at_min
|Show script_tags created before date (format: 2014-04-25T16:15:47-04:00)
+
|Return only the script tags created after the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
|updated_at_min
+
!created_at_max
|Show script_tags last updated after date (format: 2014-04-25T16:15:47-04:00)
+
|Return only the script tags created before the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
|updated_at_max
+
!updated_at_min
|Show script_tags last updated before date (format: 2014-04-25T16:15:47-04:00)
+
|Return only the script tags updated after the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
|src
+
!updated_at_max
|Show script tags with a given URL
+
|Return only the script tags updated before the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
|fields
+
!fields
|comma-separated list of fields to include in the response
+
|A comma-separated list of fields to return in the response.
 
|}
 
|}
  
 +
==== Example Request and Response ====
  
<span class="h3">Get a list of all script tags for your shop.</span>
+
<pre>
 +
GET /api/script_tags.json
  
<code>GET /admin/script_tags.json</code>
+
HTTP/1.1 200 OK
  
<span class="h4">Response</span>
 
<pre>
 
HTTP/1.1 200 OK
 
 
{
 
{
 
   "script_tags": [
 
   "script_tags": [
 
     {
 
     {
       "id": 421379493,
+
       "id": 12343,
       "src": "https:\/\/js-aplenty.com\/bar.js",
+
       "src": "https://test.spiffyserver.com/global/address_finder.js?key=4EK23454567878HMAPNT",
 
       "event": "onload",
 
       "event": "onload",
      "created_at": "2017-03-15T13:27:53-04:00",
+
       "display_scope": "order_checkout",
      "updated_at": "2017-03-15T13:27:53-04:00",
+
       "created_at": "2017-04-12T17:15:07.873+10:00",
       "display_scope": "all"
+
       "updated_at": "2017-04-12T17:15:07.873+10:00"
    },
+
     }, ...
    {
 
      "id": 596726825,
 
      "src": "https:\/\/js-aplenty.com\/foo.js",
 
      "event": "onload",
 
       "created_at": "2017-03-15T13:27:53-04:00",
 
       "updated_at": "2017-03-15T13:27:53-04:00",
 
      "display_scope": "all"
 
     }
 
 
   ]
 
   ]
 
}
 
}
</pre>
 
 
  
<span class="h3">Get a list of all script tags after the specified ID</span>
+
Examples using filters
  
<code>GET /admin/script_tags.json?since_id=421379493</code>
+
GET /api/script_tags.json?fields=id,src,display_scope
  
<span class="h4">Response</span>
 
<pre>
 
HTTP/1.1 200 OK
 
{
 
  "script_tags": [
 
    {
 
      "id": 596726825,
 
      "src": "https:\/\/js-aplenty.com\/foo.js",
 
      "event": "onload",
 
      "created_at": "2017-03-15T13:27:53-04:00",
 
      "updated_at": "2017-03-15T13:27:53-04:00",
 
      "display_scope": "all"
 
    }
 
  ]
 
}
 
 
</pre>
 
</pre>
  
 +
=== <code>GET /api/script_tags/count.json</code> ===
  
<span class="h3">Get script tags with a particular URL</span>
+
Return a count of the number of script tags.
  
<code>GET /admin/script_tags.json?src=https://js-aplenty.com/foo.js</code>
+
==== Optional Parameters ====
  
<span class="h4">Response</span>
+
{| class="reference"
<pre>
+
!since_id
HTTP/1.1 200 OK
+
|Limit the results to only include objects which have an id greater than the given value.
{
+
|-
  "script_tags": [
+
!src
    {
+
|Limit the results to only include script tags with the given source URL.
      "id": 596726825,
+
|-
      "src": "https:\/\/js-aplenty.com\/foo.js",
+
!created_at_min
      "event": "onload",
+
|Return only the script tags created after the given date and time. Use the format "2014-12-31 12:00".
      "created_at": "2017-03-15T13:27:53-04:00",
+
|-
      "updated_at": "2017-03-15T13:27:53-04:00",
+
!created_at_max
      "display_scope": "all"
+
|Return only the script tags created before the given date and time. Use the format "2014-12-31 12:00".
    }
+
|-
  ]
+
!updated_at_min
}
+
|Return only the script tags updated after the given date and time. Use the format "2014-12-31 12:00".
</pre>
+
|-
 
+
!updated_at_max
 
+
|Return only the script tags updated before the given date and time. Use the format "2014-12-31 12:00".
<span class="api-endpoint-request"><span class="api-endpoint-request-type api-endpoint-request-type-get">GET</span> /admin/script_tags/count.json </span>
 
 
 
{| class="wikitable" style="width: 100%"
 
|style="width: 30%"| src
 
|Count script tags with given URL
 
 
|}
 
|}
  
 +
==== Example Request and Response ====
  
<span class="h3">Get a count of all script tags for your shop.</span>
+
<pre>
 +
GET /api/script_tags/count.json
  
<code>GET /admin/script_tags/count.json</code>
+
HTTP/1.1 200 OK
  
<span class="h4">Response</span>
 
<pre>
 
HTTP/1.1 200 OK
 
 
{
 
{
   "count": 2
+
   "count": 4
 
}
 
}
 +
 
</pre>
 
</pre>
  
 +
=== <code>GET /api/script_tags/SCRIPT_TAG_ID.json</code> ===
  
 +
Retrieves a single script tag by ID.
  
<span class="api-endpoint-request"><span class="api-endpoint-request-type api-endpoint-request-type-get">GET</span> /admin/script_tags/596726825.json</span>
+
==== Optional Parameters ====
  
{| class="wikitable" style="width: 100%"
+
{| class="reference"
|style="width: 30%"| fields
+
!fields
|comma-separated list of fields to include in the response
+
|A comma-separated list of fields to return in the response.
 
|}
 
|}
  
 +
==== Example Request and Response ====
  
<span class="h3">Get a single script tag by its ID.</span>
+
<pre>
 +
GET /api/script_tags/12343.json
  
<code>GET /admin/script_tags/#{id}.json</code>
+
HTTP/1.1 200 OK
  
<span class="h4">Response</span>
 
<pre>
 
HTTP/1.1 200 OK
 
 
{
 
{
 
   "script_tag": {
 
   "script_tag": {
     "id": 596726825,
+
     "id": 12343,
     "src": "https:\/\/js-aplenty.com\/foo.js",
+
     "src": "https://test.spiffyserver.com/global/address_finder.js?key=4EK23454567878HMAPNT",
 
     "event": "onload",
 
     "event": "onload",
     "created_at": "2017-03-15T13:27:53-04:00",
+
    "display_scope": "order_checkout",
     "updated_at": "2017-03-15T13:27:53-04:00",
+
     "created_at": "2017-04-12T17:15:07.873+10:00",
    "display_scope": "all"
+
     "updated_at": "2017-04-12T17:15:07.873+10:00"
 
   }
 
   }
 
}
 
}
 
</pre>
 
</pre>
  
 +
=== <code>POST /api/script_tags.json</code> ===
  
 +
Create a new script tag.
  
<span class="api-endpoint-request"><span class="api-endpoint-request-type api-endpoint-request-type-get">POST</span> /admin/script_tags.json</span>
+
==== Example Request and Response ====
  
<span class="h3">Trying to create a script tag without a src and event will return an error</span>
 
 
<pre class="plain">
 
POST /admin/script_tags.json
 
{
 
  "script_tag": {
 
    "body": "foobar"
 
  }
 
}
 
</pre>
 
 
<span class="h4">Response</span>
 
 
<pre>
 
<pre>
HTTP/1.1 422 Unprocessable Entity
+
POST /api/script_tags.json
{
 
  "errors": {
 
    "src": [
 
      "can't be blank",
 
      "Source must be secure (HTTPS)"
 
    ],
 
    "event": [
 
      "can't be blank",
 
      "is not included in the list"
 
    ]
 
  }
 
}
 
</pre>
 
  
 
<span class="h3">Create a new script tag</span>
 
 
<pre class="plain">
 
POST /admin/script_tags.json
 
 
{
 
{
 
   "script_tag": {
 
   "script_tag": {
 +
    "src": "https://js-library.com/widgets.js",
 
     "event": "onload",
 
     "event": "onload",
     "src": "https:\/\/djavaskripped.org\/fancy.js"
+
     "display_scope": "online_store"
 
   }
 
   }
}</pre>
+
}
  
<span class="h4">Response</span>
 
<pre>
 
 
HTTP/1.1 201 Created
 
HTTP/1.1 201 Created
{
 
  "script_tag": {
 
    "id": 870402689,
 
    "src": "https:\/\/djavaskripped.org\/fancy.js",
 
    "event": "onload",
 
    "created_at": "2017-03-15T13:28:16-04:00",
 
    "updated_at": "2017-03-15T13:28:16-04:00",
 
    "display_scope": "all"
 
  }
 
}
 
 
</pre>
 
</pre>
  
 +
=== <code>PUT /api/script_tags/SCRIPT_TAG_ID.json</code> ===
  
 +
Updates a script tag.
  
<span class="api-endpoint-request"><span class="api-endpoint-request-type api-endpoint-request-type-get">PUT</span> /admin/script_tags/596726825.json</span>
+
==== Example Request and Response ====
  
<span class="h3">Update a script tag's URL</span>
+
<pre>
 +
PUT /api/script_tags/12343.json
  
<pre class="plain">
 
PUT /admin/script_tags/#{id}.json
 
 
{
 
{
 
   "script_tag": {
 
   "script_tag": {
     "id": 596726825,
+
     "id": 12343,
     "src": "https:\/\/somewhere-else.com\/another.js"
+
     "src": "https://another-library.com/new_widget.js"
 
   }
 
   }
 
}
 
}
</pre>
 
  
<span class="h4">Response</span>
 
<pre>
 
 
HTTP/1.1 200 OK
 
HTTP/1.1 200 OK
{
 
  "script_tag": {
 
    "id": 596726825,
 
    "src": "https:\/\/somewhere-else.com\/another.js",
 
    "event": "onload",
 
    "created_at": "2017-03-15T13:27:53-04:00",
 
    "updated_at": "2017-03-15T13:28:14-04:00",
 
    "display_scope": "all"
 
  }
 
}
 
 
</pre>
 
</pre>
  
 +
=== <code>DELETE /api/script_tags/SCRIPT_TAG_ID.json</code> ===
  
 +
Deletes a script tag.
  
<span class="api-endpoint-request"><span class="api-endpoint-request-type api-endpoint-request-type-get">DELETE</span> /admin/script_tags/596726825.json</span>
+
==== Example Request and Response ====
  
<span class="h3">Remove an existing script tag from a shop</span>
+
<pre>
 +
DELETE /api/script_tags/12312.json
  
<pre class="plain">
+
HTTP/1.1 200 OK
DELETE /admin/script_tags/#{id}.json
 
</pre>
 
  
<span class="h4">Response</span>
 
<pre>
 
HTTP/1.1 200 OK
 
 
{}
 
{}
 
</pre>
 
</pre>
 
<br><br><br>
 
  
 
== Further Reference ==
 
== Further Reference ==

Latest revision as of 12:38, 14 June 2018

The ScriptTag resource represents remote JavaScript code that is loaded into the pages of a store's shopfront or the checkout pages. This lets you add functionality to these pages without needing to update any theme templates.

Script tags are scoped to the app that created them. When an app is uninstalled from a store, all of the script tags associated with it are automatically removed.

ScriptTag Properties

id
{ "id" : 191 }

A unique numeric identifier for the script tag.

src
{ "src" : "https://js-library.com/widget.js" }

The URL of the remote script that is to be included on the page.

event
{ "event": "onload" }

The DOM event that triggers the loading of the script. Valid values are:

  • onload
display_scope
{ "display_scope": "online_store" }

The page or pages where the script should be included. Valid values are:

  • online_store: Include the script only on the shopfront pages
  • order_checkout: Include the script on the checkout pages
  • all: Include the script on all pages.
created_at
{ "created_at": "2008-07-15T20:00:00-04:00" }

The date and time (ISO 8601 format) when the script tag was created.

updated_at
{ "updated_at": "2008-07-16T20:00:00-04:00" }

The date and time (ISO 8601 format) when the script tag was last updated.

Endpoints

GET /api/script_tags.json

Retrieve a list of all script tags.

Optional Parameters

limit Number of results returned. The default is 30, with a maximum of 50 in a single request.
page The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
since_id Limit the results to only include objects which have an id greater than the given value.
src Limit the results to only include script tags with the given source URL.
created_at_min Return only the script tags created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the script tags created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the script tags updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the script tags updated before the given date and time. Use the format "2014-12-31 12:00".
fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/script_tags.json

HTTP/1.1 200 OK

{
  "script_tags": [
    {
      "id": 12343,
      "src": "https://test.spiffyserver.com/global/address_finder.js?key=4EK23454567878HMAPNT",
      "event": "onload",
      "display_scope": "order_checkout",
      "created_at": "2017-04-12T17:15:07.873+10:00",
      "updated_at": "2017-04-12T17:15:07.873+10:00"
    }, ...
  ]
}

Examples using filters

GET /api/script_tags.json?fields=id,src,display_scope

GET /api/script_tags/count.json

Return a count of the number of script tags.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
src Limit the results to only include script tags with the given source URL.
created_at_min Return only the script tags created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the script tags created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the script tags updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the script tags updated before the given date and time. Use the format "2014-12-31 12:00".

Example Request and Response

GET /api/script_tags/count.json

HTTP/1.1 200 OK

{
  "count": 4
}

GET /api/script_tags/SCRIPT_TAG_ID.json

Retrieves a single script tag by ID.

Optional Parameters

fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/script_tags/12343.json

HTTP/1.1 200 OK

{
  "script_tag": {
    "id": 12343,
    "src": "https://test.spiffyserver.com/global/address_finder.js?key=4EK23454567878HMAPNT",
    "event": "onload",
    "display_scope": "order_checkout",
    "created_at": "2017-04-12T17:15:07.873+10:00",
    "updated_at": "2017-04-12T17:15:07.873+10:00"
  }
}

POST /api/script_tags.json

Create a new script tag.

Example Request and Response

POST /api/script_tags.json

{
  "script_tag": {
    "src": "https://js-library.com/widgets.js",
    "event": "onload",
    "display_scope": "online_store"
  }
}

HTTP/1.1 201 Created

PUT /api/script_tags/SCRIPT_TAG_ID.json

Updates a script tag.

Example Request and Response

PUT /api/script_tags/12343.json

{
  "script_tag": {
    "id": 12343,
    "src": "https://another-library.com/new_widget.js"
  }
}

HTTP/1.1 200 OK

DELETE /api/script_tags/SCRIPT_TAG_ID.json

Deletes a script tag.

Example Request and Response

DELETE /api/script_tags/12312.json

HTTP/1.1 200 OK

{}

Further Reference