Difference between revisions of "API ScriptTag"

From Spiffy Stores Knowledge Base
m
 
(9 intermediate revisions by one other user not shown)
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
 +
|<pre>{ "display_scope": "online_store" }</pre>
 +
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
 +
|<pre>{ "created_at": "2008-07-15T20:00:00-04:00" }</pre>
 +
The date and time (ISO 8601 format) when the script tag was created.
 +
|-
 +
!updated_at
 +
|<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.
 +
|}
  
−
==What you can do with ScriptTag==
+
== Endpoints ==
  
−
The Spiffy Stores API lets you do the following with the ScriptTag resource. More detailed versions of these general actions may be available:
+
=== <code>GET /api/script_tags.json</code> ===
  
−
* GET /admin/script_tags.json<br>Receive a list of all ScriptTags
+
Retrieve a list of all script tags.
−
* 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
 
  
 +
==== Optional Parameters ====
  
−
==ScriptTag properties==
+
{| class="reference"
−
 
+
!limit
−
<html>
+
|Number of results returned. The default is 30, with a maximum of 50 in a single request.
−
  <style type="text/css">
+
|-
−
  table.wikitable td { padding: 10px 20px !important; text-align: left; vertical-align: top; }
+
!page
−
  table.wikitable pre {padding: 0 !important; border: none !important; }
+
|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.
−
  </style>
+
|-
−
</html>
+
!since_id
−
{| class="wikitable" style="width: 100%"
+
|Limit the results to only include objects which have an id greater than the given value.
−
|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.
+
!src
−
|-
+
|Limit the results to only include script tags with the given source URL.
−
|event
+
|-
−
|<pre>"event": "onload"</pre><br>DOM event which triggers the loading of the script. Valid values are: "onload."
+
!created_at_min
 +
|Return only the script tags created after the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
−
|id
+
!created_at_max
−
|<pre>"id": 596726825</pre><br>The unique numeric identifier for the ScriptTag.
+
|Return only the script tags created before the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
−
|src
+
!updated_at_min
−
|<pre>"src": "https://js-aplenty.com/foo.js"</pre><br>Specifies the location of the ScriptTag.
+
|Return only the script tags updated after the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
−
|display_scope
+
!updated_at_max
−
|<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.
+
|Return only the script tags updated before the given date and time. Use the format "2014-12-31 12:00".
 
|-
 
|-
−
|updated_at
+
!fields
−
|<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.
+
|A comma-separated list of fields to return in the response.
 
|}
 
|}
  
 +
==== Example Request and Response ====
  
−
== Endpoints==
+
<pre>
−
<html>
+
GET /api/script_tags.json
−
<style type="text/css">
 
  
−
.api-endpoint-request {
+
HTTP/1.1 200 OK
−
  padding: 15px 30px;
 
−
  display: block;
 
−
  background: #30373b;
 
−
  color: #fff;
 
−
}
 
  
−
.api-endpoint-request-type {
+
{
−
   display: block;
+
   "script_tags": [
−
  float: left;
+
    {
−
  background: #2a2c2e;
+
      "id": 12343,
−
  padding: 15px 30px;
+
      "src": "https://test.spiffyserver.com/global/address_finder.js?key=4EK23454567878HMAPNT",
−
  margin: -15px 30px 0 -30px;
+
      "event": "onload",
−
   color: #fff;
+
      "display_scope": "order_checkout",
 +
      "created_at": "2017-04-12T17:15:07.873+10:00",
 +
      "updated_at": "2017-04-12T17:15:07.873+10:00"
 +
    }, ...
 +
   ]
 
}
 
}
  
−
.api-endpoint-description {
+
Examples using filters
−
  padding: 15px 30px;
 
−
  display: block;
 
−
  background: #f9fafa;
 
−
  border-bottom: 0;
 
−
}
 
  
−
.api-endpoint-content, .api-endpoint-description {
+
GET /api/script_tags.json?fields=id,src,display_scope
−
  border: 1px solid #e5e5e5;
 
−
  border-top: 0;
 
−
}
 
  
−
.api-endpoint-queryparameters {
+
</pre>
−
  border-top: 1px solid #e5e5e5;
 
−
}
 
  
−
.api-endpoint-queryparameters table {
+
=== <code>GET /api/script_tags/count.json</code> ===
−
  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 {
+
Return a count of the number of script tags.
−
  padding: 15px;
 
−
  border-right: 1px solid #e5e5e5;
 
−
  border-bottom: 1px solid #e5e5e5;
 
−
  vertical-align: top;
 
−
}
 
  
−
.h3 {
+
==== Optional Parameters ====
−
  font-weight: 500;
 
−
  -webkit-font-smoothing: antialiased;
 
−
  display: block;
 
−
  margin-bottom: 0.55em;
 
−
  color: #30373b;
 
−
  font-size: 1.125em;
 
−
  line-height: 1.5;
 
−
}
 
  
−
.h4 {
+
{| class="reference"
−
  font-weight: 500;
+
!since_id
−
  -webkit-font-smoothing: antialiased;
+
|Limit the results to only include objects which have an id greater than the given value.
−
  display: block;
 
−
  margin-bottom: 0.55em;
 
−
  color: #30373b;
 
−
  font-size: 1.025em;
 
−
  line-height: 1.5;
 
−
}
 
−
</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 to show (default: 1)
 
−
|-
 
−
|since_id
 
−
|Restrict results to after the specified ID
 
 
|-
 
|-
−
|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
 
−
|comma-separated list of fields to include in the response
 
 
|}
 
|}
  
−
<span class="h3">Get a list of all script tags for your shop.</span>
+
==== Example Request and Response ====
  
−
<pre>GET /admin/script_tags.json</pre>
+
<pre>
 +
GET /api/script_tags/count.json
  
−
<span class="h4>Response</span>
+
HTTP/1.1 200 OK
 +
 
 +
{
 +
  "count": 4
 +
}
 +
 
 +
</pre>
 +
 
 +
=== <code>GET /api/script_tags/SCRIPT_TAG_ID.json</code> ===
 +
 
 +
Retrieves a single script tag by ID.
 +
 
 +
==== Optional Parameters ====
 +
 
 +
{| class="reference"
 +
!fields
 +
|A comma-separated list of fields to return in the response.
 +
|}
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
GET /api/script_tags/12343.json
  
−
<code>
 
 
HTTP/1.1 200 OK
 
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"
 +
  }
 +
}
 +
</pre>
 +
 +
=== <code>POST /api/script_tags.json</code> ===
 +
 +
Create a new script tag.
 +
 +
==== Example Request and Response ====
 +
 +
<pre>
 +
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
 +
</pre>
 +
 +
=== <code>PUT /api/script_tags/SCRIPT_TAG_ID.json</code> ===
 +
 +
Updates a script tag.
 +
 +
==== Example Request and Response ====
 +
 +
<pre>
 +
PUT /api/script_tags/12343.json
 +
 
{
 
{
−
   "script_tags": [
+
   "script_tag": {
−
     {
+
     "id": 12343,
−
      "id": 421379493,
+
     "src": "https://another-library.com/new_widget.js"
−
      "src": "https:\/\/js-aplenty.com\/bar.js",
+
  }
−
      "event": "onload",
 
−
      "created_at": "2017-03-15T13:27:53-04:00",
 
−
      "updated_at": "2017-03-15T13:27:53-04:00",
 
−
      "display_scope": "all"
 
−
    },
 
−
     {
 
−
      "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"
 
−
    }
 
−
  ]
 
 
}
 
}
−
</code>
+
 
−
<br><br><br>
+
HTTP/1.1 200 OK
 +
</pre>
 +
 
 +
=== <code>DELETE /api/script_tags/SCRIPT_TAG_ID.json</code> ===
 +
 
 +
Deletes a script tag.
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
DELETE /api/script_tags/12312.json
 +
 
 +
HTTP/1.1 200 OK
 +
 
 +
{}
 +
</pre>
  
 
== Further Reference ==
 
== Further Reference ==

Latest revision as of 11: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

Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=API_ScriptTag&oldid=7314"