Difference between revisions of "API ScriptTag"

From Spiffy Stores Knowledge Base
m
 
(23 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 shop's storefront 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".
 
  
−
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.
+
{| 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:
  
−
==What you can do with ScriptTag==
+
* onload
 +
|-
 +
!display_scope
 +
|<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:
+
* 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.
 +
|}
  
−
* GET /admin/script_tags.json<br>Receive a list of all ScriptTags
+
== Endpoints ==
−
* 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
 
  
 +
=== <code>GET /api/script_tags.json</code> ===
  
−
<br><br><br>
+
Retrieve a list of all script tags.
 +
 
 +
==== Optional Parameters ====
 +
 
 +
{| class="reference"
 +
!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 <code>limit</code> 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 ====
 +
 
 +
<pre>
 +
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
 +
 
 +
</pre>
 +
 
 +
=== <code>GET /api/script_tags/count.json</code> ===
 +
 
 +
Return a count of the number of script tags.
 +
 
 +
==== Optional Parameters ====
 +
 
 +
{| class="reference"
 +
!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 ====
 +
 
 +
<pre>
 +
GET /api/script_tags/count.json
 +
 
 +
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
 +
 
 +
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_tag": {
 +
    "id": 12343,
 +
    "src": "https://another-library.com/new_widget.js"
 +
  }
 +
}
 +
 
 +
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"