## 1. Project Overview & Quickstart (productdevbook/LICENSE)

# LICENSE

Open-source repository productdevbook/LICENSE

### Repository Details
- **Repository:** [productdevbook/LICENSE](https://github.com/productdevbook/LICENSE)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (productdevbook/docs)

## File: README.md

# Website

This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

```
$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

---

## File: docs/custom-props/for-custom-events.md

---
title: Attach custom properties to custom events
---

import useBaseUrl from '@docusaurus/useBaseUrl';

:::note
Custom properties is an upcoming premium feature that's free-to-use during the private preview. Pricing will be announced soon.
:::

The process of attaching custom properties to your custom events is different depending on how you're sending your events to Plausible.

## 1. Using the `tagged-events` script extension

Here's how you can attach custom properties if you're tracking your custom events with the `tagged-events` script extension.

In this case, your tracking script should already include the `tagged-events`` script extension:

```html
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.tagged-events.js"></script>
```

Now, let's say you have a contact form both in the header and footer of your site. In addition to tracking submissions, you might want to know which section of your site the form was submitted on. Instead of creating separate goals for each form, you can send a custom property instead:

Similarly to how you define an event name inside the `class` attribute, you can use the format `plausible-event-=<value>` to define custom properties. Following the same example, your code might look something like this:

```html

  
  <form class="plausible-event-name=Form+Submit plausible-event-position=header">...</form>

  
  <form class="plausible-event-name=Form+Submit plausible-event-position=footer">...</form>

```

Now, both form submissions would trigger the same `Form Submit` event, but the `position` property will be different.

:::note
To represent a space character in property values, you can use a `+` sign. This is because you can't include the space character in the `class` attribute.
:::

You can add up to 30 classes for custom properties. Simply separate them with a space character like in the above example.

## 2. Using the manual method

If you're sending your custom events manually with JavaScript, for example:

```js
plausible('Download')
```

All you have to do is add the second argument to this function call with the custom properties as follows:

```js
plausible('Download', {props: {method: 'HTTP', position: 'footer'}})
```

---

## File: docs/custom-props/for-pageviews.md

---
title: Attach custom properties to pageviews
---

import useBaseUrl from '@docusaurus/useBaseUrl';

:::note
Custom properties is an upcoming premium feature that's free-to-use during the private preview. Pricing will be announced soon.
:::

## 1. Change the Plausible snippet on your site

The easiest option to get started is to use the `script.pageview-props.js` script extension. Please change the file name in the `src` attribute of your Plausible snippet from `script.js` to `script.pageview-props.js`. It should look like this:

```html
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.pageview-props.js"></script>
```

Or if you're using [a proxy](/proxy/introduction.md):

```html
<script defer data-domain="yourdomain.com" src="https://yourproxy.com/script.pageview-props.js"></script>
```

:::note
If you're using any of our other script extensions, you can [combine them](script-extensions.md#you-can-combine-extensions-according-to-your-needs) by changing the `src` attribute in the snippet. If you want to track pageview props and outbound link clicks simultaneously, change the script name to `script.pageview-props.outbound-links.js`.
:::

## 2. Add your custom properties to your Plausible snippet

You should now add the custom properties as HTML attributes to your Plausible snippet (the `<script>` element). The attributes must follow the format `event-="<value>"`. For example, if you want to track the `author` property with a value of `John Doe`, you should do that as follows:

```html
<script defer event-author="John Doe" data-domain="yourdomain.com" src="https://plausible.io/js/script.pageview-props.js"></script>
```

You can add up to 30 custom properties alongside a pageview by adding multiple attributes:

```html
<script defer event-author="John Doe" event-logged_in="true" event-darkmode="true" data-domain="yourdomain.com" src="https://plausible.io/js/script.pageview-props.js"></script>
```

All properties provided in the snippet will automatically be attached to any [custom event conversions](custom-event-goals.md) as well.

That's it! You're now tracking custom properties alongside pageviews.

## Using `script.manual.js` as an alternative

As an alternative, you can also use our `manual` script extension to send custom properties for pageviews. It works exactly the same way as with [custom properties for custom events](/custom-props/for-custom-events#2-using-the-manual-method). Make sure to write `pageview` exactly the same as in the following example:

```javascript
plausible('pageview', {props: {author: 'John Doe', logged_in: 'false'}})
```

This will send a pageview with properties `author` and `logged_in`.

## Using a combination of `script.manual.pageview-props.js`

You can also combine the `manual` extension with the `pageview-props` extension. For example, if you're using this snippet:

```html
<script defer event-logged_in="false" data-domain="yourdomain.com" src="https://plausible.io/js/script.manual.pageview-props.js"></script>
```

and also calling the `plausible` function manually like this:

```javascript
plausible('pageview', {props: {author: 'John Doe'}})
```

Then the pageview will be sent with two properties - `author` and `logged_in`. If you provide the exact same property name in the snippet and in sending the pageview manually, the value from the manual `plausible` function call will take precedence. For example, if you do this:

```html
<script defer event-logged_in="false" data-domain="yourdomain.com" src="https://plausible.io/js/script.manual.pageview-props.js"></script>
<script>plausible('pageview', {props: {logged_in: 'true'}})</script>
```

Then the pageview will be sent with `logged_in = true`.

---

## File: docs/custom-props/introduction.md

---
title: Introduction to custom properties
---

import useBaseUrl from '@docusaurus/useBaseUrl';

:::note
Custom properties is an upcoming premium feature that's free-to-use during the private preview. Pricing will be announced soon.
:::

You can attach custom properties (also known as custom dimensions in Google Analytics) when sending pageviews or custom events to Plausible in order to create custom metrics. Custom properties allow you to collect and analyze metrics that we don't track automatically. 

For example, say you want to track your blog posts by `author`. Every time a visitor lands on one of the posts, you can send a pageview with the property `author=...`. You can then filter your Plausible dashboard by a specific author to see all the relevant stats for the posts published by that particular writer.

Some other examples of stats you can get by sending custom properties:

* Filter content by the publication date, page type, ID, tag or category
* Filter visitors by login status or user role
* Filter visitors by language they're viewing your website in
* Filter visitors by how many prefer or use the dark mode
* Filter visitors by level completions or high score if you're a game developer
* Filter by the segment that saw a particular variation of your site which is useful for A/B testing

## Personally identifiable information

Note that you must ensure that no personally identifiable information (PII) is sent to Plausible with custom properties. PII is information that could be used on its own to identify, contact, or precisely locate an individual. This includes:

* full names or usernames
* email addresses
* mailing addresses
* phone numbers
* credit card information
* passport numbers
* precise locations
* IP addresses
* pseudonymous cookie IDs, advertising IDs or other pseudonymous end user identifiers

## `(none)` values

Plausible will display `(none)` in your dashboard when you send a custom property key with no value, or `null`/`undefined` as a value. Also, when you send one event with a property (e.g. `author`) and another event with the same name, but without the `author` property, then you will also see the `(none)` value because the property has not been sent with every event.

## Accepted values

Custom properties only accept scalar values such as strings, numbers and booleans. Data structures such as objects, arrays etc. aren't accepted.

## Limits

* You can send up to 30 different custom properties per event
* The number of allowed characters for a property name is 300
* The limit for custom property values is 2000 characters 

## Set up custom property tracking

Please check out the following sections of instructions for setting up the tracking and analyzing the data in your dashboard:

* [Attach custom properties to pageviews](/custom-props/for-pageviews)
* [Attach custom properties to custom events](/custom-props/for-custom-events)
* [Analyze your traffic by custom properties](/custom-props/props-dashboard)

---

## File: docs/custom-props/props-dashboard.md

---
title: Analyze your traffic by custom properties
---

import useBaseUrl from '@docusaurus/useBaseUrl';

:::note
Custom properties is an upcoming premium feature that's free-to-use during the private preview. Pricing will be announced soon.
:::

## 1. Configure properties in your site settings

When you send properties to Plausible, they won't show up in your dashboard automatically. You'll have to configure the property for the numbers to show up.

To configure a property, go to the [site settings](website-settings.md) in your Plausible account and visit the "**Custom Properties**" section. You should see an empty list with a prompt to add a property. 



You also have the option to add all properties that you've already sent with one click.




## 2. Filter by a custom property

As soon as you have at least one event or one pageview with a custom property attached to it, you will be able to see an option to filter by that property in your Plausible dashboard. 

At the bottom of your dashboard, in the "**Goal Conversions**" section you can switch to the "**Properties**" tab. There you can select a property to see the related data. You can also click on any of your custom events in the  "**Goals**" tab which will then display the properties attached to that event.



You can also open the filter dropdown menu and select "**Property**". In that view you can interact with the dropdown fields, where Plausible will automatically provide filtering suggestions based on the custom properties that we have recorded. The suggestions also take into account the selected time period and other filters already applied.



Choose the custom property that you want to analyze and click on "**Apply Filter**" to filter your dashboard. Note that you can only filter by one custom property at a time.

---

## File: docs/proxy/guides/akamai.md

---
title: Proxying Plausible through Akamai
---

import useBaseUrl from '@docusaurus/useBaseUrl';

Proxying Plausible through your own property on Akamai is easy, fast and privacy-friendly. 

:::note
The instructions assume you use the default paths ``/js/script.js`` and ``/api/event``. You can change these based on your preferences.
:::

## Step 1: Proxy Analytics Script

This Rule Group serves incoming requests matching ``/js/script.js`` directly from the Akamai edge caches. In case of a cache miss the request is forwarded to ``plausible.io`` in a privacy-friendly way.

### Add new Rule Group 

In Akamai Property Manager add a new Rule Group ``Plausible (Script)`` with these settings:



### Set Criteria

- Path matches one off: ``/js/script.js``

### Add Behaviour: Caching

- Caching Option: **Cache**
- Force revalidation of stale objects: **Serve stale if unable to validate**
- Maxage: ``6 hours``

### Add Behaviour: Origin Server

- Origin Type: **Your origin**
- Origin Server Hostname: ``plausible.io``
- Forward Host Header: **Origin Hostname**
- Cache Key Hostname: **Origin Hostname**
- Supports Gzip Compression: **Yes**
- Send True Client IP Header: **No** _(Privacy: No need to expose IP)_
- Verification Settings: **Choose your own**
- ... _(Other settings can be left as is)_

## Step 2: Proxy Event API

This Rule Group forwards incoming requests matching ``/api/event`` to plausible.io. It adds extra headers (``X-Forwarded-Proto``, ``X-Forwarded-Host`` and ``X-Forwarded-For``) to the outgoing request, so your Plausible statistics are complete. For privacy & security reasons incoming cookies are removed before sending to ``plausible.io``.

### Add new Rule Group 

In Akamai Property Manager add a new Rule Group ``Plausible (Event API)`` with these settings:



### Set Criteria

- Path matches one off: ``/api/event``

### Add Behaviour: Origin Server

- Origin Type: **Your origin**
- Origin Server Hostname: ``plausible.io``
- Forward Host Header: **Origin Hostname**
- Cache Key Hostname: **Origin Hostname**
- Supports Gzip Compression: **Yes**
- Send True Client IP Header: **Yes**
- True Client IP Header Name: ``X-Forwarded-For``
- Verification Settings: **Choose your own**
- ... _(Other settings can be left as is)_



### Add Behaviour: Modify Outgoing Request Header

- Action: **Add**
- Header Name: ``X-Forwarded-Proto``
- Header Value: ``{{builtin.AK_SCHEME}}``

### Add Behaviour: Modify Outgoing Request Header

- Action: **Add**
- Header Name: ``X-Forwarded-Host``
- Header Value: ``{{builtin.AK_HOST}}``

### Add Behaviour: Modify Outgoing Request Header

- Action: **Remove**
- Header Name: ``cookie`` _(Privacy: No need to expose cookies to origin servers)_

### Optional: 

In case you are using SureRoute, please disable it:



Thanks to [Tim Vereecke](https://www.scalemates.com/), Akamai's web performance architect, for these instructions!

---

## File: docs/proxy/guides/apache.md

---
title: Proxying Plausible through Apache HTTP Server
---

If you're already running Apache HTTP Server as your main web server or reverse
proxy, you can also configure it to proxy your analytics. Start by adjusting your configuration as shown in the next step.

## Step 1: Enable the required modules

```
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod ssl
```

## Step 2: Update your config
```
<VirtualHost *:80>
  ServerName website.com

  ProxyRequests off
  ProxyPreserveHost off
  SSLProxyEngine on

  <Location /js/script.js>
    ProxyPass https://plausible.io/js/script.js
    ProxyPassReverse https://plausible.io/js/script.js
  </Location>

  <Location /api/event>
    ProxyPass https://plausible.io/api/event
    ProxyPassReverse https://plausible.io/api/event
  </Location>

</VirtualHost>
```

## Step 3: Adjust your deployed script

With the above config in place, you can change the script tag on your site as follows:

```html
<script defer data-api="/api/event" data-domain="website.com" src="/js/script.js"></script>
```

That's it! You're now using a proxy.

## Alternative reverse proxy written in PHP for shared hosting on Apache

As an alternative to the above, there's also a reverse proxy for Plausible Analytics written in PHP for shared hostings on Apache. [See details here](https://github.com/Neoflow/ReverseProxy-PlausibleAnalytics).

---

## File: docs/proxy/guides/caddy.md

---
title: Proxying Plausible through Caddy
---

If you're already running Caddy as your main web server or reverse
proxy, you can also configure it to proxy your analytics. Start by adjusting your
configuration as shown in the next step.

## Step 1: Update your Caddyfile

Add the following to your Caddyfile:

```
@plausible path /js/script.js /api/event
handle @plausible {
	# Change this if you use a different variant of the script
	# e.g. rewrite /js/script.js /js/script.outbound-links.js
	rewrite /js/script.js /js/script.js
	reverse_proxy https://plausible.io {
		header_up Host {http.reverse_proxy.upstream.hostport}
	}
}
```

## Step 2: Adjust your deployed script

With the above config in place, you can change the script tag on your site as follows:

```html
<script defer data-api="/api/event" data-domain="website.com" src="/js/script.js"></script>
```

Courtesy: [Francis Lavoie](https://caddy.community/u/francislavoie/summary) (@francislavoie) on a [Caddy Community post](https://caddy.community/t/how-to-proxy-plausible-analytics/12679/5).

---

## File: docs/proxy/guides/cloudflare.md

---
title: Proxying Plausible through Cloudflare
---

import useBaseUrl from '@docusaurus/useBaseUrl';

You can use Cloudflare Workers to proxy your Plausible Analytics requests. Cloudflare Workers offers free service for up to 100,000 requests per day.
All you need to set it up is a free Cloudflare account.

Here's the step-by-step process for creating a proxy. It takes only a few minutes and requires no tech know-how or prior experience.

Step 0: Sign up for a free Cloudflare account if you don't have an account already and add your site.

## Step 1: Create a worker

In your Cloudflare account, click on the 'Workers & Pages' section in the sidebar to get the 'Overview' page. On the top right of the 'Overview' page, click on the 'Create application' button. On the 'Create an application' page click on the 'Create Worker' button in the 'Workers' tab to start configuring your proxy. 

## Step 2 (Optional): You can change your service name

This is optional but you can change the service name to give your worker a more meaningful name. Do avoid words like 'plausible', 'analytics', 'tracking', 'stats', etc. as they may be blocked. It's also fine to keep the random name that Cloudflare generates by default. 

## Step 3: Paste the following code

Then click on the 'Deploy' button. Next click on the 'Edit Code' button, remove the default code that Cloudflare presents and paste the code that we present below instead.

We recommend you change the folder name in the first two lines in the code below. This makes your proxy more difficult to discover and block. We especially recommend you change the folder name in the two lines if you're not hosting your site on the Cloudflare CDN.

In the **ScriptName** line, change the `/js/` to whatever you wish. Say `/your-folder-name/`. Then the location in the code would be `/your-folder-name/script.js`. 

In the **Endpoint** line, change the `/api/` to whatever you want. It can be the same as above but you can also choose something different. If you choose `/your-folder-name/`, then the full location would be `/your-folder-name/event`. 

Do avoid words like 'plausible', 'analytics', 'tracking', 'stats', etc. as they may be blocked.

```js
const ScriptName = '/js/script.js';
const Endpoint = '/api/event';

const ScriptWithoutExtension = ScriptName.replace('.js', '')

addEventListener('fetch', event => {
    event.passThroughOnException();
    event.respondWith(handleRequest(event));
})

async function handleRequest(event) {
  const pathname = new URL(event.request.url).pathname
  const [baseUri, ...extensions] = pathname.split('.')

  if (baseUri.endsWith(ScriptWithoutExtension)) {
      return getScript(event, extensions)
  } else if (pathname.endsWith(Endpoint)) {
      return postData(event)
  }
  return new Response(null, { status: 404 })
}

async function getScript(event, extensions) {
    let response = await caches.default.match(event.request);
    if (!response) {
        response = await fetch("https://plausible.io/js/plausible." + extensions.join("."));
        event.waitUntil(caches.default.put(event.request, response.clone()));
    }
    return response;
}

async function postData(event) {
    const request = new Request(event.request);
    request.headers.delete('cookie');
    return await fetch("https://plausible.io/api/event", request);
}
```

Once you've added the above code to the worker, you can click on the 'Save and Deploy' button on the top right. On the confirmation message, do confirm that you want to save and deploy your worker by clicking on the 'Save and Deploy' button again.

## Step 4: Make sure the script is accessible

Now, the Plausible script should be accessible at the following URL:

```
https://your-worker-name.your-cloudflare-username.workers.dev/your-folder-name/script.js
```

If you can load this URL and see some JavaScript code, you should be good to go to the following step.

## Step 5: Integrate a new snippet into your site header

Once you have the URL for your script, you can replace your Plausible Analytics script tag in the Header (`<head>`) section of your site with the proxied snippet. This is how the new snippet should look like (make sure to edit it to have the correct domain name of your site and the correct URL to the proxied file):

```html
<script defer data-domain="yourdomain.com" data-api="https://your-worker-name.your-cloudflare-username.workers.dev/your-folder-name/event" src="https://your-worker-name.your-cloudflare-username.workers.dev/your-folder-name/script.js"></script>
```

Are you using our extensions such as hash-based routing, page exclusions or outbound link click tracking? Change the file name from `script.js` to the script you want to use: `script.hash.js`, `script.exclusions.js` or `script.outbound-links.js`. Want to use more than one extension? You can chain them like this: `script.hash.exclusions.outbound-links.js`. You just need to change the script name in the snippet that you insert into your site, no need to change the code for the worker.

That's it! You're now counting your website stats using a proxy.

## Step 6 (Optional): Run proxy as a subdirectory

If you're hosting your site on the Cloudflare CDN, you can run the proxy as a subdirectory installation to avoid a third-party
request to the `workers.dev` domain. This is completely optional but it can make your URLs look much cleaner and avoid third-party
requests.

In your Cloudflare account, click on the 'Workers & Pages' section in the sidebar. Then, click on the worker that you have just created and then click on the 'View' button in the 'Routes' section of your worker. Next click on the 'Add route' button in the top right.

Next, in the 'Route' field enter the URL prefix where you would like to install Plausible. In this example, we'll install the proxy on the `example.com` domain, and we'll use `qwerty` as the subdirectory name. You can choose any name for the subdirectory, but it's a good idea to avoid words like 'analytics' and 'tracking'.

* Route: `*example.com/qwerty/*`

Then select your domain name in the 'Zone' field. Then click on the 'Add route' button. After clicking 'Add route', the script should be accessible at the subdirectory URL of your site: `https://example.com/qwerty/your-folder-name/script.js`. 

At this point you can change your Plausible script tag in your site header to reference the new URL. It's also important to specify the `data-api` attribute to make sure data is sent through the worker as well. The new snippet in your site header should look like this:

```html
<script defer data-domain="yourdomain.com" data-api="/qwerty/your-folder-name/event" src="/qwerty/your-folder-name/script.js"></script>
```

Notice that since the script tag is installed on the same domain as the website itself, there's no need to specify the hostname in `src` and `data-api` attributes. A relative path will work just fine.

---

## File: docs/proxy/guides/cloudfront.md

---
title: Proxying Plausible through CloudFront
---

## Step 1: Create new origin

First we need to create a new origin pointing to the Plausible server. In the CloudFront console, under your distribution; create a new origin:

-   Origin Domain Name: `plausible.io`
-   Origin Protocol Policy: `HTTPS Only`

## Step 2: Create custom behaviours

Now we need to define some custom behaviour for when to use our new origin. In the CloudFront console, under your distribution; create new behaviour.

First for the analytics script:

- Path Pattern: `/js/script.js` (you can use `/js/script.*` to also match [script extensions](https://plausible.io/docs/script-extensions))
- Origin or Origin Group: The origin we created in step 1
- Viewer Protocol Policy: `HTTPS Only`
- Allowed HTTP Methods: `GET, HEAD`

And another for the event API:

- Path Pattern: `/api/event`
- Origin or Origin Group: The origin we created in step 1
- Viewer Protocol Policy: `HTTPS Only`
- Allowed HTTP Methods: `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`
- Origin Request Policy: `Managed-UserAgentRefererHeaders`

## Step 3: Adjust your deployed script

With the custom origin and behaviours in place, you can change your script tag as follows:

```html
<script defer data-domain="yourdomain.com" src="/js/script.js"></script>
```

Deploy these changes to your CloudFront site. You can verify the proxy is working by opening your network tab. You should see a request to
`https://yourdomain.com/js/script.js` with status 200 and another one to `https://yourdomain.com/api/event` with status 202.

Using our extensions such as hash-based routing, page exclusions or outbound link click tracking? Change the file name from script.js to the script you want to use: script.hash.js, script.exclusions.js or script.outbound-links.js. Want to use more than one extension? You can chain them like this: script.hash.exclusions.outbound-links.js.

Thanks to [@thomasjsn](https://github.com/thomasjsn) for contributing these instructions!