Diagnose widgets
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets/diagnostics';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.getsitecontrol.com/v1/sites/1/widgets/diagnostics \ --header 'Authorization: Bearer <token>'Why widgets do not show: the first call for “my widget is not showing”, “it
shows on the wrong pages” or “I get no responses”. Without widget_id it
checks the site (served at all, our code installed, any widget on) and gives
one short row per active widget with its worst cause; with widget_id it
checks that widget in the order visitors meet it: on and published, A/B test,
schedule, targeting, stop rules, trigger, whether answers are sent, and where
it showed. Views are the shows Widget statistics count. Each check has a stable reason code, what to do (next_action),
who can do it (who) and facts in values; read who before promising
anything.
It reads the saved widget, as visitors get it, and changes nothing. Views are
facts, not proof that the current settings show: install is unknown when
nothing proves the code either way. At most the 100 newest active widgets are
checked. The meaning of every code and how to word it: the guide
widgets.diagnostics.read.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”A widget id from List widgets, to check it whole
A widget id from List widgets, to check it whole
Responses
Section titled “Responses”object
Blocking when a check (or every widget checked) blocks; unknown when site or widget could not be read; warning when a check warns or is unknown, an unknown install included; else ok
The requested widget; null without widget_id
object
Where the widget sits on the page, named as in the admin. modal: a window centred over the page. bar: a strip across the top or bottom of the page. panel: a box attached to the bottom of the screen, opened from its header. slide_in: a box that slides in from a corner. sidebar: a panel attached to the left or right edge of the screen. fullscreen: covers the whole screen. inline: placed inside the page content. other: a layout the admin no longer offers. “Pop-up” is not a layout: users call any widget a pop-up.
One short row per active widget; null with widget_id
object
Active widgets per state; those beyond the 100 checked are unknown
object
More widgets than the 20 listed
Blocking first, then warning, unknown, ok; newest first within one
object
Where the widget sits on the page, named as in the admin. modal: a window centred over the page. bar: a strip across the top or bottom of the page. panel: a box attached to the bottom of the screen, opened from its header. slide_in: a box that slides in from a corner. sidebar: a panel attached to the left or right edge of the screen. fullscreen: covers the whole screen. inline: placed inside the page content. other: a layout the admin no longer offers. “Pop-up” is not a layout: users call any widget a pop-up.
Ok: nothing found. warning: some visitors, pages, times or widgets do not get it, or a likely mistake. blocking: no visitor gets it. unknown: the source or the rules could not be read, or (install) nothing proves it either way.
The worst check; null when ok or not checked
Shows in the last 7 days; null when unknown
Without widget_id: site, install, active_widgets. With it: site, install, widget, ab_test, schedule, targeting, frequency, trigger, submit_flow, games, views
object
Site: whether the site’s widgets are served at all. install: whether our code is on the site. active_widgets: whether any widget is on. widget: on, and in what visitors load. ab_test: its share in an A/B test. schedule, targeting, trigger: its rules. frequency: its stop rules. submit_flow: whether answers are sent. games: whether a game still has placeholder prize codes. views: where and how often it showed.
Ok: nothing found. warning: some visitors, pages, times or widgets do not get it, or a likely mistake. blocking: no visitor gets it. unknown: the source or the rules could not be read, or (install) nothing proves it either way.
Why, a stable code; null when ok
None: nothing to do. contact_support: write to support. upgrade_plan, check_billing: the billing screen. activate_site: turn the site on. check_installation: “Check code” in the admin. enable_app_embed: turn on the app embed at values.shopify.enable_url. turn_on_widget: update_widgets with is_active: true. edit_schedule, edit_targeting, set_trigger: the widget’s targeting. edit_content: the widget’s pages and buttons.
User: an editor of the site fixes it. owner: the account owner, for money, the plan and turning sites on. support: a person on our side decides; never promise the outcome. none: nobody needs to act.
Facts of the check, {} when none. site: limited_on. install: site_last_view_on, site_views_7d, viewed_hosts (host to views, 7 days), rendered_at (when what visitors load was last updated), shopify (null without a Shopify store: readable, embed_enabled, metafield_ok, script_tag, theme_name, enable_url, script_tags_end_on). active_widgets: active, inactive, checked. widget: saved_at, published_at, last_switch (the newest list_widget_history entry), history_since. ab_test: group_id, variants, share. schedule: ended_on, schedule. targeting: pages, all_pages, audience, audience_keys, findings (each reason, state, patterns). frequency: stop. trigger: start, hide. submit_flow: pages (position, ref), unread. games: fields (name, codes). views: last_view_on, views_7d, saved_at, views_after_save_day, by_page, by_device. The schedule, pages, audience, start, hide and stop blocks are those of get_widget; engine: rules marks rules this check does not read. Days are UTC days.
{ "state": "ok", "widget": { "layout": "modal" }, "widgets": { "items": [ { "layout": "modal", "state": "ok", "check": "site", "reason": "blocked_suspicious_activity" } ] }, "checks": [ { "check": "site", "state": "ok", "reason": "blocked_suspicious_activity", "next_action": "none", "who": "user" } ]}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
widget_not_found: the site has no such widget, or it was deleted
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds