diff --git a/docs/sites-api.md b/docs/sites-api.md index a26740ac..6140f975 100644 --- a/docs/sites-api.md +++ b/docs/sites-api.md @@ -11,6 +11,7 @@ The Plausible Site provisioning API offers a way to create and manage sites in y * Create a new site * Delete an existing site * Change a domain name +* Configure tracker script settings * Get a site by domain * Find or create a shared link by name (to use for the [embed dashboard functionality](embed-dashboard.md)) * List existing goals @@ -154,18 +155,39 @@ Creates a site in your Plausible account. ```bash title="Try it yourself" curl -X POST https://plausible.io/api/v1/sites \ -H "Authorization: Bearer ${TOKEN}" \ - -F 'domain="test-domain.com"' \ - -F 'timezone="Europe/London"' + -H "Content-Type: application/json" \ + -d '{ + "domain": "test-domain.com", + "timezone": "Europe/London", + "tracker_script_configuration": { + "file_downloads": true, + "form_submissions": true, + "outbound_links": true + } + }' ``` ```json title="Response 200 OK" { "domain": "test-domain.com", - "timezone": "Europe/London" + "timezone": "Europe/London", + "custom_properties": [], + "tracker_script_configuration": { + "id": "pa-1iQepzD1J73BaHey2csUp", + "installation_type": null, + "track_404_pages": false, + "hash_based_routing": false, + "outbound_links": true, + "file_downloads": true, + "revenue_tracking": false, + "tagged_events": false, + "form_submissions": true, + "pageview_props": false + } } ``` -#### Post body parameters +#### Body parameters
**domain** @@ -184,31 +206,62 @@ ID of the team under which the created site is to be put. Defaults to the ID of
+**tracker_script_configuration** + +Configuration object for the tracker script for this site. When not provided, the default configuration is set. When provided or provided partially (all options are optional), allows you to customize tracking features (any option that is not specified is set to the default value). See [Tracker script configuration](#tracker-script-configuration). + +
+ ### PUT /api/v1/sites/:site_id -Update an existing site in your Plausible account. Note: currently only `domain` change is allowed. +Update an existing site in your Plausible account. You can change the domain name and/or update tracker script configuration. ```bash title="Try it yourself" curl -X PUT https://plausible.io/api/v1/sites/test-domain.com \ -H "Authorization: Bearer ${TOKEN}" \ - -F 'domain="new-test-domain.com"' + -H "Content-Type: application/json" \ + -d '{ + "domain": "new-test-domain.com", + "tracker_script_configuration": { + "form_submissions": true + } + }' ``` ```json title="Response 200 OK" { "domain": "new-test-domain.com", - "timezone": "Europe/London" + "timezone": "Europe/London", + "custom_properties": [], + "tracker_script_configuration": { + "id": "pa-1iQepzD1J73BaHey2csUp", + "installation_type": null, + "track_404_pages": false, + "hash_based_routing": false, + "outbound_links": false, + "file_downloads": false, + "revenue_tracking": false, + "tagged_events": false, + "form_submissions": true, + "pageview_props": false + } } ``` -#### Post body parameters +#### Body parameters
-**domain** +**domain** Domain of the site to be created in Plausible. Must be a globally unique, the request will fail if the domain is already taken.
+**tracker_script_configuration** + +Configuration object for the tracker script for this site. When not provided, the current configuration is kept. When provided or provided partially, allows you to update settings for tracking features (any option that is not specified is kept at the current value). See [Tracker script configuration](#tracker-script-configuration). + +
+ ### DELETE /api/v1/sites/:site_id Deletes a site from your Plausible account along with all its data and configuration. The API key must belong to the owner of the site. @@ -227,7 +280,7 @@ curl -X DELETE https://plausible.io/api/v1/sites/test-domain.com \ ### GET /api/v1/sites/:site_id -Gets details of a site. Your Plausible account must have access to it. +Gets details of a site. Your Plausible account must have access to it. The response includes the tracker script configuration for the site and its ID, which you can use to request the tracker script for this site. See [Tracker script URL](#tracker-script-url). ```bash title="Try it yourself" curl -X GET https://plausible.io/api/v1/sites/test-domain.com \ @@ -238,7 +291,19 @@ curl -X GET https://plausible.io/api/v1/sites/test-domain.com \ { "domain": "test-domain.com", "timezone": "Europe/London", - "custom_properties": ["logged_in"] + "custom_properties": ["logged_in"], + "tracker_script_configuration": { + "id": "pa-1iQepzD1J73BaHey2csUp", + "installation_type": null, + "track_404_pages": false, + "hash_based_routing": false, + "outbound_links": false, + "file_downloads": false, + "revenue_tracking": false, + "tagged_events": false, + "form_submissions": false, + "pageview_props": false + } } ``` @@ -250,9 +315,11 @@ Finds or creates a shared link for a given `site_id` (use the site domain as the ```bash title="Try it yourself" curl -X PUT https://plausible.io/api/v1/sites/shared-links \ -H "Authorization: Bearer ${TOKEN}" \ - -F 'site_id="test-domain.com"' \ - -F 'name="Wordpress"' -``` + -H "Content-Type: application/json" \ + -d '{ + "site_id": "test-domain.com", + "name": "Wordpress" + }' ```json title="Response 200 OK" { @@ -346,10 +413,12 @@ Finds or creates a goal for a given `site_id` (use the site domain as the ID). T ```bash title="Try it yourself" curl -X PUT https://plausible.io/api/v1/sites/goals \ -H "Authorization: Bearer ${TOKEN}" \ - -F 'site_id="test-domain.com"' \ - -F 'goal_type="event"' \ - -F 'event_name="Signup"' -``` + -H "Content-Type: application/json" \ + -d '{ + "site_id": "test-domain.com", + "goal_type": "event", + "event_name": "Signup" + }' ```json title="Response 200 OK" { @@ -400,8 +469,10 @@ Deletes a goal from your Plausible account. The API key must belong to the owner ```bash title="Try it yourself" curl -X DELETE https://plausible.io/api/v1/sites/goals/1 \ -H "Authorization: Bearer ${TOKEN}" \ - -F 'site_id="test-domain.com"' -``` + -H "Content-Type: application/json" \ + -d '{ + "site_id": "test-domain.com" + }' ```json title="Response 200 OK" { @@ -484,11 +555,14 @@ For a given `site_id` (use the site domain as the ID), finds an invitation or ex ```bash title="Try it yourself" curl -X PUT https://plausible.io/api/v1/sites/guests \ - -H "Authorization: Bearer ${TOKEN}" \ - -F 'site_id="test-domain.com"' \ - -F 'role="viewer"' \ - -F 'email="alice@example.com"' - ``` + -H "Authorization: Bearer ${TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "site_id": "test-domain.com", + "role": "viewer", + "email": "alice@example.com" + }' +``` ```json title="Response 200 OK" { @@ -555,3 +629,21 @@ curl -X GET https://plausible.io/api/v1/sites?after=AFTER_VALUE_FROM_LAST_RESPON ``` The `limit` parameter must remain the same when paginating, either by leaving it at a default value or passing the same value each time explicitly. The `null` value in `before` or `after` means there are no more previous or next pages to navigate to, respectively. + +## Tracker script configuration + +This parameter is used to configure the tracker script for a site. It is a JSON object with the following parameters, all of which are optional. + +- **installation_type**: Type of installation (`"wordpress"`, `"manual"`, `"gtm"`, `null`). Defaults to `null`. +- **track_404_pages**: Whether to track 404 page visits. Defaults to `false`. +- **hash_based_routing**: Whether to track hash-based routing changes. Defaults to `false`. +- **outbound_links**: Whether to track outbound link clicks. Defaults to `false`. +- **file_downloads**: Whether to track file downloads. Defaults to `false`. +- **revenue_tracking**: Whether to enable revenue tracking. Defaults to `false`. +- **tagged_events**: Whether to enable tagged events. Defaults to `false`. +- **form_submissions**: Whether to track form submissions. Defaults to `false`. +- **pageview_props**: Whether to enable pageview properties. Defaults to `false`. + +### Tracker script URL + +The resolved configuration is returned in GET/PUT/POST site endpoints response along with an ID. This ID can be used to request the tracker script for this site from the URL `https://plausible.io/js/{id}.js`.