# Session Token Authentication.
Source: https://medama.mintlify.app/api-reference/auth/session-token-authentication

post /auth/login
Login to the service and retrieve a session token for authentication.



# Session Token Logout.
Source: https://medama.mintlify.app/api-reference/auth/session-token-logout

post /auth/logout
Logout of the service and destroy the session token.



# Authentication
Source: https://medama.mintlify.app/api-reference/authentication

Example overview page before API endpoints

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas et eros iaculis tortor dapibus cursus. Curabitur quis sapien nec tortor dictum gravida.

```bash
'Authorization': 'Token <team_token>'
```

## API Tokens

Nullam convallis mauris at nunc consectetur, ac imperdiet leo rutrum. Maecenas cursus purus a pellentesque blandit. Pellentesque vitae lacinia libero, non mollis metus.

Nam id ullamcorper urna, at rutrum enim. [Maecenas vulputate](/introduction) vehicula libero, vitae sodales augue pretium nec. Quisque a magna tempor, semper risus vel, fermentum nunc. Pellentesque fermentum interdum ex, eu convallis massa blandit sed. Aliquam bibendum ipsum vel laoreet auctor.

### Permissions

Etiam lobortis ut odio ut fermentum. Nunc odio velit, sollicitudin at consectetur id, tristique eget turpis. Aliquam at risus vitae dolor sodales venenatis. In hac habitasse platea dictumst.

Aenean consequat diam eget mollis fermentum. [Quisque eu malesuada](/introduction) felis, non dignissim libero.


# Login
Source: https://medama.mintlify.app/api-reference/authentication/login

post /auth/login
Login to the service and retrieve a session token for authentication.



# Logout
Source: https://medama.mintlify.app/api-reference/authentication/logout

post /auth/logout
Logout of the service and destroy the session token.



# Update User
Source: https://medama.mintlify.app/api-reference/endpoint/update

PUT https://api.mintlify.com/api/user
This endpoint updates an existing user.

### Body

<ParamField body="name" type="string">
  This is the name of the user group.
</ParamField>

<ParamField body="user_group_id" type="string">
  This is the ID you use to identify this user group in your database.
</ParamField>

<ParamField body="mapping" type="object">
  This is a JSON mapping of schema id to either the data source that this user
  group should be associated with or id of the datasource you provided when
  creating it.
</ParamField>

<ParamField body="properties" type="object">
  This is a JSON object for properties assigned to this user group. These will
  be accessible through variables in the dashboards and SQL editor
</ParamField>

### Response

<ResponseField name="success" type="number">
  Indicates whether the call was successful. 1 if successful, 0 if not.
</ResponseField>

<ResponseField name="user_group" type="object">
  The contents of the user group

  <Expandable title="Toggle object">
    <ResponseField name="team_id" type="number">
      Indicates whether a new user group was created.
    </ResponseField>

    <ResponseField name="token" type="string">
      This is the user group token (userGroupToken or USER\_GROUP\_TOKEN) that will be
      used to identify which user group is viewing the dashboard. You should save
      this on your end to use when rendering an embedded dashboard.
    </ResponseField>

    <ResponseField name="name" type="string">
      This is the name of the user group provided in the request body.
    </ResponseField>

    <ResponseField name="provided_id" type="string">
      This is the user\_group\_id provided in the request body.
    </ResponseField>

    <ResponseField name="properties" type="JSON | Null">
      This is the properties object if it was provided in the request body
    </ResponseField>

    <ResponseField name="api_environment_tag" type="JSON or null">
      This is the environment tag of the user group. Possible values are 'Customer'
      and 'Testing'
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Example Request
  curl --location --request PUT 'https://api.mintlify.com/api/user' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token <token>' \
  --data-raw '{
      "user_group_id": "example_1",
      "name": "Example 1",
      "mapping": {"40": "213", "134": "386"},
      "properties": {"filterValue": "value"}
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "success": 1,
    "user_group": {
      "team_id": 113,
      "token": "<user_group_token_to_auth_dashboard>",
      "name": "ok",
      "provided_id": "6"
    }
  }
  ```
</ResponseExample>


# Ping
Source: https://medama.mintlify.app/api-reference/event/ping

get /event/ping
Ping endpoint to determine if the user is unique or not.



# Send Hit Event
Source: https://medama.mintlify.app/api-reference/event/send-hit-event

post /event/hit
Send a hit event to register a user view or interaction.



# Unique User Check.
Source: https://medama.mintlify.app/api-reference/event/unique-user-check

get /event/ping
This is a ping endpoint to determine if the user is unique or not.



# Introduction
Source: https://medama.mintlify.app/api-reference/introduction

Simple integration with your systems.

<Warning>This project is currently in version 0.x. We reserve the right to make breaking changes to the API in this early access. Any breaking changes will follow Semver standards and occur only during minor releases.</Warning>

This guide provides a quick overview of the available API endpoints, enabling you to integrate our analytics easily into your personal or professional dashboards to monitor website performance.

Our frontend Single Page Application (SPA) is built using the same API, serving as a practical reference for your implementation.  Additionally, each analytics instance hosts an `openapi.yaml` file at `/openapi.yaml` for easy integration with your own OpenAPI clients.

## Authentication

To access the API, all requests (except `Event`) must include a cookie named `_me_sess`, which you can obtain from the `/auth/login` endpoint.

## Errors

| Code | Description                                                                                                                                |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 400  | Bad Request - Ensure the request is correctly formatted.                                                                                   |
| 401  | Unauthorized - Ensure you are authenticated.                                                                                               |
| 403  | Forbidden - Ensure you have the correct permissions to view the page.                                                                      |
| 404  | Not Found - Ensure the resource exists.                                                                                                    |
| 409  | Conflict - The resource already exists.                                                                                                    |
| 429  | Too Many Requests - You have exceeded the rate limit.                                                                                      |
| 500  | Internal Server Error - This is an unhandled bug on our end. Please report it by creating an [issue](https://github.com/medama-io/medama). |


# Get Resource Usage
Source: https://medama.mintlify.app/api-reference/settings/get-resource-usage

get /settings/usage
Get the current CPU, memory and disk usage of the server.



# Update Resource Usage
Source: https://medama.mintlify.app/api-reference/settings/update-resource-usage

patch /settings/usage
Update the resource usage settings of the server.



# Get Browser Stats
Source: https://medama.mintlify.app/api-reference/stats/get-browser-stats

get /website/{hostname}/browsers
Get a list of browsers and their stats.



# Get Country Stats
Source: https://medama.mintlify.app/api-reference/stats/get-country-stats

get /website/{hostname}/countries
Get a list of countries and their stats.



# Get Device Stats
Source: https://medama.mintlify.app/api-reference/stats/get-device-stats

get /website/{hostname}/devices
Get a list of devices and their stats.



# Get Language Stats
Source: https://medama.mintlify.app/api-reference/stats/get-language-stats

get /website/{hostname}/languages
Get a list of languages and their stats.



# Get OS Stats
Source: https://medama.mintlify.app/api-reference/stats/get-os-stats

get /website/{hostname}/os
Get a list of OS and their stats.



# Get Page Stats
Source: https://medama.mintlify.app/api-reference/stats/get-page-stats

get /website/{hostname}/pages
Get a list of pages and their stats.



# Get Property Stats
Source: https://medama.mintlify.app/api-reference/stats/get-property-stats

get /website/{hostname}/properties
Get a list of custom properties and their stats. If a property name is provided, it will return the stats for that property instead.



# Get Referrer Stats
Source: https://medama.mintlify.app/api-reference/stats/get-referrer-stats

get /website/{hostname}/referrers
Get a list of referrers and their stats.



# Get Stat Summary
Source: https://medama.mintlify.app/api-reference/stats/get-stat-summary

get /website/{hostname}/summary
Get a summary of the website's stats.



# Get Time Stats
Source: https://medama.mintlify.app/api-reference/stats/get-time-stats

get /website/{hostname}/time
Get a list of pages and their time stats.



# Get UTM Campaign Stats
Source: https://medama.mintlify.app/api-reference/stats/get-utm-campaign-stats

get /website/{hostname}/campaigns
Get a list of UTM campaigns and their stats.



# Get UTM Medium Stats
Source: https://medama.mintlify.app/api-reference/stats/get-utm-medium-stats

get /website/{hostname}/mediums
Get a list of UTM mediums and their stats.



# Get UTM Source Stats
Source: https://medama.mintlify.app/api-reference/stats/get-utm-source-stats

get /website/{hostname}/sources
Get a list of UTM sources and their stats.



# Delete User
Source: https://medama.mintlify.app/api-reference/user/delete-user

delete /user
Delete a user account.



# Get Resource Usage
Source: https://medama.mintlify.app/api-reference/user/get-resource-usage

get /user/usage
Get the current CPU, memory and disk usage of the server.



# Get User Info
Source: https://medama.mintlify.app/api-reference/user/get-user-info

get /user
Retrieve the information of the user with the matching user ID.



# Update User Info
Source: https://medama.mintlify.app/api-reference/user/update-user-info

patch /user
Update a user account's details.



# Add Website
Source: https://medama.mintlify.app/api-reference/website/add-website

post /websites
Add a new website.



# Delete Website
Source: https://medama.mintlify.app/api-reference/website/delete-website

delete /websites/{hostname}
Delete a website.



# Get Website
Source: https://medama.mintlify.app/api-reference/website/get-website

get /websites/{hostname}
Get website details for an individual website.



# List Websites
Source: https://medama.mintlify.app/api-reference/website/list-websites

get /websites
Get a list of all websites from the user.



# Update Website
Source: https://medama.mintlify.app/api-reference/website/update-website

patch /websites/{hostname}
Update a website's information.



# CLI
Source: https://medama.mintlify.app/config/cli

Server-side configuration.

The binary executable is a command-line interface (CLI) that allows you to configure how the analytics instance behaves. This document outlines the available commands and their usage.

## Commands

* `start`: Starts the analytics server.
* `version`: Displays the version of the analytics server.

## `start`

The following flags can be used with the `start` command:

```sh Available Flags
Usage of start:
  -analyticsdb string
    	Path to analytics database. (default "./me_analytics.db")
  -appdb string
    	Path to app database. (default "./me_meta.db")
  -autossl string
    	Automatically provision SSL certificates to the specified domain and redirect HTTP requests to HTTPS.

    	Requires the server to run on ports 80 and 443. The domain must be publicly accessible and resolve to the server.
  -autosslemail string
    	Email address to optionally send SSL certificate notifications.
  -corsorigins string
    	Comma separated list of allowed CORS origins on API routes. Useful for external dashboards that may host the frontend on a different domain.
  -demo
    	Enable demo mode restricting all POST/PATCH/DELETE actions (except login).
  -env
    	Opt-in to allow environment variables to be used for configuration. Flags will still override environment variables.
  -level string
    	Logger level (debug, info, warn, error) (default "info")
  -logger string
    	Logger format (json, pretty) (default "json")
  -port int
    	Port to listen on. (default 8080)
  -profiler
    	Enable debug profiling.
```

Example usage:

```sh Example Command
./medama-executable start -env -port=8080 -logger=pretty -level=debug -corsorigins=http://localhost:8080,http://localhost:3000
```


# Environment Variables
Source: https://medama.mintlify.app/config/environment-variables

Server-side configuration.

The binary executable can also be configured using environment variables.

Note, you must opt-in to this by setting the `-env` flag when starting the server. This mode of configuration is useful for containerized environments like Docker where it is difficult to pass command-line arguments.

<Info>If you are using the pre-built Docker images, this flag has already been set.</Info>

## Variables

* `APP_DATABASE_HOST`: Path to app database. Default is `./me_meta.db`.

* `ANALYTICS_DATABASE_HOST`: Path to analytics database. Default is `./me_analytics.db`.

* `AUTO_SSL`: Automatically provision SSL certificates to the specified domain and redirect HTTP requests to HTTPS. Requires the server to run on ports 80 and 443. The domain must be publicly accessible and resolve to the server.

* `AUTO_SSL_EMAIL`: Email address to optionally send SSL certificate notifications.

* `PORT`: Port to listen on. Default is `8080`.

* `LOGGER`: Logger format. Default is `json`. Options are `json` and `pretty`.

* `LEVEL`: Logger level. Default is `info`. Options are `debug`, `info`, `warn`, and `error`.

* `CORS_ALLOWED_ORIGINS`: Comma-separated list of allowed CORS origins on API routes. Useful for external dashboards that may host the frontend on a different domain.


# Tracking Snippet
Source: https://medama.mintlify.app/config/tracking-snippet

Configuring how the tracking snippet behaves.

The tracking snippet is a small piece of JavaScript code that you embed into your website to track visitor interactions. This document outlines how the tracking snippet works and how you can configure it.

## Installation

Your tracking snippet is hosted on your analytics server. To install it on your website, you need to include the following script tag in the `<head>` section of your website:

```html
<script defer src="https://[your-analytics-server].com/script.js"></script>
```

## Configuration

The tracking snippet can be configured using the following options:

| Option      | Description                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| `data-api`  | Optional hostname + path to the analytics server. Default is the domain where the script is being hosted. |
| `data-hash` | Include this to track browser navigations for websites that use a hash router.                            |

Here's an example of a fully configured tracking snippet:

```html Example
<script defer src="https://[where-your-script-is-hosted].com/script.js" data-api="[different-analytics-server].com/api/" data-hash></script>
```


# Docker
Source: https://medama.mintlify.app/deployment/docker

Run your container anywhere.

While using Docker is not necessary for this project, it simplifies deployment for a variety of environments. The pre-built Docker images are available on the [GitHub Container Registry](https://github.com/medama-io/medama/pkgs/container/medama).

## Tags

| Docker Tags                                 | Description                     |
| ------------------------------------------- | ------------------------------- |
| `ghcr.io/medama-io/medama:latest`           | Latest stable release.          |
| `ghcr.io/medama-io/medama:edge`             | Latest development build.       |
| `ghcr.io/medama-io/medama:<version>`        | Specific version.               |
| `ghcr.io/medama-io/medama:sha-<commit-sha>` | Specific commit (short format). |

## Setup

<Steps>
  <Step title="Run Container">
    <AccordionGroup>
      <Accordion title="Docker Run" icon="docker">
        Create a Docker volume to store the database files:

        ```sh
        docker volume create medama-data
        ```

        Then run the container with the following command:

        ```sh
        docker run -d -p 8080:8080 -v medama-data:/app/data ghcr.io/medama-io/medama:latest
        ```

        <Info>All database data is stored in the `/app/data` directory within the containers. You can create a volume or use bind mounts to redirect where data is stored on your local system. Learn more about Docker volumes [here](https://docs.docker.com/storage/volumes/).</Info>
      </Accordion>

      <Accordion title="Docker Compose" icon="cubes">
        If you prefer using Docker Compose, create a `docker-compose.yml` file with the following content:

        ```yaml
        version: '3'

        services:
            medama:
                image: ghcr.io/medama-io/medama:latest
                ports:
                    - "8080:8080"
                volumes:
                    - medama-data:/app/data

        volumes:
            medama-data:
        ```

        Then start the container with the following command:

        ```sh
        docker-compose up -d
        ```

        <Tip>Docker Compose is a great solution for setting up reverse proxies, such as Nginx or Caddy, which can automatically provision SSL certificates and handle traffic routing.</Tip>
      </Accordion>

      <Accordion title="Build from source" icon="github">
        If you want to build from source using Docker, clone the `medama-io/medama` repository and build the image from there:

        ```sh
        git clone https://github.com/medama-io/medama

        docker build -t medama .
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Configure Deployment">
    Before you can start collecting data, you may want to configure your analytics instance to suit your needs.  It is recommended to refer to the [Environment Variables](/config/environment-variables) configuration page.

    These variables can be set using the `-e` flag in `docker run` or the `environment` property in Docker Compose.

    Afterwards, ensure your analytics instance is configured to be accessible from the internet. You must also set up SSL certificates for your deployment.
  </Step>

  <Step title="Add Your First Website">
    Success! You can now add your first website to the analytics instance by visiting the web interface at `http://localhost:8080` or the publicly accessible hostname for your deployment.

    The default login credentials are:

    * Username: `admin`
    * Password: `CHANGE_ME_ON_FIRST_LOGIN`

    <Warning>To successfully login, you must either use `localhost` or a `HTTPS` connection. Logging in via an unencrypted `HTTP` connection will not work. <br /><br /> If your hosting provider does not automatically provision SSL certificates to your machine, you may want to use [the automatic SSL setup feature](../deployment/ssl).</Warning>

    <Note>It is recommended to change the username and password immediately after logging in for the first time. This can be changed in the settings menu.</Note>
  </Step>

  <Step title="Embed Tracking Snippet">
    Then, embed the following HTML tracking snippet in the `<head>` element of your website to start collecting data:

    ```html
    <script defer src="https://[your-public-api-hostname].com/script.js"></script>
    ```

    <Info>Learn more about configuring your tracking snippet [here](/config/tracking-snippet).</Info>
  <script defer src="https://demo.medama.io/script.js"></script><link rel="icon" sizes="48x48" type="image/png" href="https://demo.medama.io/favicon-48x48.png"/><link rel="icon" type="image/svg+xml" href="https://demo.medama.io/favicon.svg" /></Step>
</Steps>


# Fly.io
Source: https://medama.mintlify.app/deployment/fly

Simple deployment with an easy-to-use platform.

Deploying Medama on Fly.io is a straightforward process that can be accomplished with just a few steps.

<Info>Fly.io's Hobby plan costs \$5 per month, plus \$0.15 per GB for persistent storage. Typically, the base allowance on the Hobby plan is sufficient unless you manage large websites. You can find more details on the [pricing page](https://fly.io/docs/about/pricing).</Info>

## Setup

<Steps>
  <Step title="Install Fly CLI">
    Visit the [Fly CLI installation page](https://fly.io/docs/flyctl/install/) to install the Fly CLI on your local machine.
  </Step>

  <Step title="Login or Sign Up">
    If you don't have an account, create one. If you already have an account, log in with your credentials.
  </Step>

  <Step title="Create Directory">
    Create a new directory on your local machine and navigate to it. For example:

    ```bash
    mkdir medama-analytics
    cd medama-analytics
    ```

    This is where you will store the `fly.toml` configuration file.
  </Step>

  <Step title="Launch Application">
    Run the following command to deploy the application:

    ```bash
    fly launch --from https://github.com/medama-io/example-fly-io
    ```

    This command will clone the repository into the current directory and deploy the application to Fly.io. You will be prompted to configure various application settings such as the name, region, and VM size.
  </Step>

  <Step title="Add Your First Website">
    Success! You can now add your first website to the analytics instance by visiting the web interface at `http://localhost:8080` or the publicly accessible hostname for your deployment.

    The default login credentials are:

    * Username: `admin`
    * Password: `CHANGE_ME_ON_FIRST_LOGIN`

    <Warning>To successfully login, you must either use `localhost` or a `HTTPS` connection. Logging in via an unencrypted `HTTP` connection will not work. <br /><br /> If your hosting provider does not automatically provision SSL certificates to your machine, you may want to use [the automatic SSL setup feature](../deployment/ssl).</Warning>

    <Note>It is recommended to change the username and password immediately after logging in for the first time. This can be changed in the settings menu.</Note>
  </Step>

  <Step title="Embed Tracking Snippet">
    Then, embed the following HTML tracking snippet in the `<head>` element of your website to start collecting data:

    ```html
    <script defer src="https://[your-public-api-hostname].com/script.js"></script>
    ```

    <Info>Learn more about configuring your tracking snippet [here](/config/tracking-snippet).</Info>
  <script defer src="https://demo.medama.io/script.js"></script><link rel="icon" sizes="48x48" type="image/png" href="https://demo.medama.io/favicon-48x48.png"/><link rel="icon" type="image/svg+xml" href="https://demo.medama.io/favicon.svg" /></Step>
</Steps>

<Tip>Regularly check the Medama Analytics repository for updates and redeploy the application to ensure you are using the latest version.</Tip>


# Installation
Source: https://medama.mintlify.app/deployment/installation

Self-host, effortlessly.

This project is designed with self-hostability in mind and comes as a **single-binary with no additional database setup** that can be downloaded on [GitHub Releases](https://github.com/medama-io/medama/releases). If you are familiar with self-hosting, you can run the binary on your server immediately. If you are unsure, the following guides will help you get started.

### Environment

For most small websites, a VM with 512MB of memory is recommended. However, this project can easily scale vertically, making use of additional resources for larger websites. Storage requirements will increase gradually based on traffic.

## Deployment Guides

<CardGroup cols={2}>
  <Card title="Single Binary" icon="lightbulb" href="/deployment/single-binary">
    Single-binary deployment guide for Linux and macOS.
  </Card>

  <Card title="Docker" icon="docker" href="/deployment/docker">
    Pre-built distroless Docker images available on GitHub Container Registry.
  </Card>

  <Card title="Fly.io" icon="fly" href="/deployment/fly">
    Simple deployment to Fly.io with a pre-configured Docker image.
  </Card>

  <Card title="Railway" icon={<svg width="24" height="24" viewBox="0 0 1024 1024" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M4.756 438.175A520.713 520.713 0 0 0 0 489.735h777.799c-2.716-5.306-6.365-10.09-10.045-14.772-132.97-171.791-204.498-156.896-306.819-161.26-34.114-1.403-57.249-1.967-193.037-1.967-72.677 0-151.688.185-228.628.39-9.96 26.884-19.566 52.942-24.243 74.14h398.571v51.909H4.756ZM783.93 541.696H.399c.82 13.851 2.112 27.517 3.978 40.999h723.39c32.248 0 50.299-18.297 56.162-40.999ZM45.017 724.306S164.941 1018.77 511.46 1024c207.112 0 385.071-123.006 465.907-299.694H45.017Z" fill="#17cd8c"/><path d="M511.454 0C319.953 0 153.311 105.16 65.31 260.612c68.771-.144 202.704-.226 202.704-.226h.031v-.051c158.309 0 164.193.707 195.118 1.998l19.149.706c66.7 2.224 148.683 9.384 213.19 58.19 35.015 26.471 85.571 84.896 115.708 126.52 27.861 38.499 35.876 82.756 16.933 125.158-17.436 38.97-54.952 62.215-100.383 62.215H16.69s4.233 17.944 10.58 37.751h970.632A510.385 510.385 0 0 0 1024 512.218C1024.01 229.355 794.532 0 511.454 0Z" fill="#17cd8c"/></svg>} href="/deployment/railway">
    One-click deployment to Railway with a pre-configured Docker image.
  </Card>
</CardGroup>

### Additional Guides

<CardGroup cols={2}>
  <Card title="Automatic SSL Setup" icon="shield-check" href="/deployment/ssl">
    Automatically provision SSL certificates to your machine.
  </Card>
</CardGroup>


# Railway
Source: https://medama.mintlify.app/deployment/railway

One-click deployment with a button.

Deploying Medama on Railway is a simple process with a one-click deploy button.

<Info>Railway's Hobby plan is \$5 per month, plus \$0.25 per GB for persistent storage. You will receive \$5 in credits when you sign up. Typically, the base plan will be enough unless you manage large websites. You can find more details on the [pricing page](https://railway.app/pricing).</Info>

## Setup

<Steps>
  <Step title="Use Template">
    Click the button below to start configuring a template on Railway. Railway will handle the environment setup and deploy the application for you.

    [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/tjGZyt?referralCode=jiBqUQ)
  </Step>

  <Step title="Login or Sign Up">
    If you do not have an account, you will be prompted to create one. Otherwise, log in to your existing account.
  </Step>

  <Step title="Configure Deployment">
    Before you can start collecting data, you may want to configure your analytics instance to suit your needs.  It is recommended to refer to the [Environment Variables](/config/environment-variables) configuration page.

    The Railway template will automatically set the basic required environment variables for you.
  </Step>

  <Step title="Add Your First Website">
    Success! You can now add your first website to the analytics instance by visiting the web interface at `http://localhost:8080` or the publicly accessible hostname for your deployment.

    The default login credentials are:

    * Username: `admin`
    * Password: `CHANGE_ME_ON_FIRST_LOGIN`

    <Warning>To successfully login, you must either use `localhost` or a `HTTPS` connection. Logging in via an unencrypted `HTTP` connection will not work. <br /><br /> If your hosting provider does not automatically provision SSL certificates to your machine, you may want to use [the automatic SSL setup feature](../deployment/ssl).</Warning>

    <Note>It is recommended to change the username and password immediately after logging in for the first time. This can be changed in the settings menu.</Note>
  </Step>

  <Step title="Embed Tracking Snippet">
    Then, embed the following HTML tracking snippet in the `<head>` element of your website to start collecting data:

    ```html
    <script defer src="https://[your-public-api-hostname].com/script.js"></script>
    ```

    <Info>Learn more about configuring your tracking snippet [here](/config/tracking-snippet).</Info>
  <script defer src="https://demo.medama.io/script.js"></script><link rel="icon" sizes="48x48" type="image/png" href="https://demo.medama.io/favicon-48x48.png"/><link rel="icon" type="image/svg+xml" href="https://demo.medama.io/favicon.svg" /></Step>
</Steps>

<Tip>Regularly check the Medama Analytics repository for updates and redeploy the application to ensure you are using the latest version.</Tip>


# Single Binary
Source: https://medama.mintlify.app/deployment/single-binary

Self-host on your own platform.

This setup is very flexible, allowing you to run everything on a single server or VM. It is good option if you have spare capacity on an existing machine.

<Warning>This approach requires you to manually track new releases and update the binary yourself every time.</Warning>

## Supported Platforms

| Platform name | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `linux_amd64` | Linux AMD64                                                       |
| `linux_arm64` | Linux ARM64                                                       |
| `osx_amd64`   | macOS 12+ (Intel CPUs)                                            |
| `osx_arm64`   | macOS 12+ (Apple Silicon: M1, M2 CPUs, etc.)                      |
| `windows`     | Unsupported. Consider using [Docker](/deployment/docker) instead. |

<Info>The binary is compatible with most Linux distributions by default, including Ubuntu, CentOS, and Debian. For minimal environments, ensure the `libstdc++6` package and its dependencies are installed.</Info>

## Installation

<Steps>
  <Step title="Download">
    Get the latest version of the binary from [GitHub Releases](https://github.com/medama-io/medama/releases) that matches your operating system.
  </Step>

  <Step title="Run Program">
    Save the binary in a suitable location, then run the program with the following `start` command:

    ```sh
    ./<path-to-executable> start
    ```

    On the first run, this will create two database files in the same directory as the binary: `me_meta.db` and `me_analytics.db`. Ensure these files are kept in persistent storage.
  </Step>

  <Step title="Configure Deployment">
    Before you can start collecting data, you may want to configure your analytics instance to suit your needs. It is recommended to refer to the [CLI Configuration](/config/cli) page for more details.

    Afterwards, ensure your analytics instance is configured to be accessible from the internet. You must also set up SSL certificates for your deployment.
  </Step>

  <Step title="Add Your First Website">
    Success! You can now add your first website to the analytics instance by visiting the web interface at `http://localhost:8080` or the publicly accessible hostname for your deployment.

    The default login credentials are:

    * Username: `admin`
    * Password: `CHANGE_ME_ON_FIRST_LOGIN`

    <Warning>To successfully login, you must either use `localhost` or a `HTTPS` connection. Logging in via an unencrypted `HTTP` connection will not work. <br /><br /> If your hosting provider does not automatically provision SSL certificates to your machine, you may want to use [the automatic SSL setup feature](../deployment/ssl).</Warning>

    <Note>It is recommended to change the username and password immediately after logging in for the first time. This can be changed in the settings menu.</Note>
  </Step>

  <Step title="Embed Tracking Snippet">
    Then, embed the following HTML tracking snippet in the `<head>` element of your website to start collecting data:

    ```html
    <script defer src="https://[your-public-api-hostname].com/script.js"></script>
    ```

    <Info>Learn more about configuring your tracking snippet [here](/config/tracking-snippet).</Info>
  <script defer src="https://demo.medama.io/script.js"></script><link rel="icon" sizes="48x48" type="image/png" href="https://demo.medama.io/favicon-48x48.png"/><link rel="icon" type="image/svg+xml" href="https://demo.medama.io/favicon.svg" /></Step>
</Steps>


# Automatic SSL Setup
Source: https://medama.mintlify.app/deployment/ssl

Automatically provision SSL certificates to your machine.

If your hosting provider does not easily offer SSL certificate provisioning for your machine, you can use the `-autossl` flag or `AUTO_SSL` environment variable to automatically provision SSL certificates to the specified domain and redirect HTTP requests to HTTPS.

The flag accepts a domain name as an argument. For example:

```sh
./medama start -autossl example.com
```

This feature requires the server to run on ports 80 and 443. The domain **MUST** be publicly accessible and resolve to the server using A/AAAA records.

## FAQ

### Do I need root privileges to bind to ports 80 and 443?

On Linux, you may not have permission to bind to ports 80 and 443. You can use the following command to allow the binary to bind to these ports without requiring root privileges:

```sh
sudo setcap cap_net_bind_service=+ep /path/to/your/binary
```


# Click Events
Source: https://medama.mintlify.app/features/custom-properties/click-events



Click event tracking allows you to send custom events when a user clicks on a specific element on your website. This can be particularly useful for monitoring user interactions with elements like buttons, links, or other interactive components.

## Usage

<Steps>
  <Step title="Enable Tracker">
    First, ensure that the click event tracking feature is enabled in your dashboard settings. Navigate to the "Tracker" section and check the box for "Click Events."

    <Note>It may take up to 6 hours for returning visitors to see the updated tracking code due to caching. Ensure your CDN respects our cache headers to prevent any unexpected delays.</Note>
  </Step>

  <Step title="Attach HTML Data Attributes">
    To track a click event, include the `data-m:click` HTML attribute on an element. This attribute should be a key-value pair that will be sent with the event.

    The following example demonstrates how to attach custom properties to a click event:

    ```html
    <!DOCTYPE html>
    <html>
    	<body>
    		<button data-m:click="action=purchase;product_id=123">Buy Now</button>
    		<a href="/contact" data-m:click="action=contact">Contact Us</a>
    	</body>
    </html>
    ```

    In this example, a click event with `{ "action": "purchase", "product_id": "123" }` will be sent when the "Buy Now" button is clicked, and `{ "action": "contact" }` will be sent when the "Contact Us" link is clicked.

    You can set these attributes statically or dynamically based on user interactions or other relevant information.

    <Tip>Multiple properties can be separated by semi-colons.</Tip>
  </Step>

  <Step title="View Events">
    Once the tracking code is updated on your website, you can view the custom properties in the event list on your dashboard. Each event will include the custom properties attached to the page view, allowing you to filter and segment your data based on these properties.
  </Step>
</Steps>


# Overview
Source: https://medama.mintlify.app/features/custom-properties/overview



Custom properties are a powerful feature that allow you to attach additional metadata to your events. This can be valuable for adding extra context about your users, such as their subscription status, whether they are logged in, or any other custom data you wish to track.

## Types

Medama supports multiple types of custom property tracking, which can be individually opted into through your dashboard settings:

<CardGroup cols={2}>
  <Card title="Page View Events" icon="code" href="/features/custom-properties/page-events">
    Attach custom properties to your page views to include additional metadata about your users.
  </Card>

  <Card title="Click Events" icon="arrow-pointer" href="/features/custom-properties/click-events">
    Send a custom event when a user clicks on a specific element on your website.
  </Card>
</CardGroup>

## Usage

The dashboard provides a simple interface to filter and segment your data based on custom properties. You can select which custom properties to display in the event list, and filter events based on these properties.

![Custom Properties Selector](https://mintlify.s3.us-west-1.amazonaws.com/medama/img/custom-prop-select.png)

Each custom property is stored as a key-value pair, allowing you to filter and segment your data based on these properties.

![Custom Properties Filter](https://mintlify.s3.us-west-1.amazonaws.com/medama/img/custom-prop-filter.png)

Each event is linked to a specific page view, allowing for custom properties to be filtered alongside regular page view filters. This makes it easy to analyze how different user segments interact with your website.

<Warning>
  When using custom properties, it's crucial to ensure that you are not sending any sensitive information that could be used to identify individual users due to data privacy regulations.
</Warning>


# Page Events
Source: https://medama.mintlify.app/features/custom-properties/page-events



Page event tracking allows you to include additional metadata about your users when they visit a specific page on your website. This feature is useful for segmenting users based on their state, such as whether they are logged in or which color theme they have selected.

## Usage

<Steps>
  <Step title="Enable Tracker">
    First, ensure that the page event tracking feature is enabled in your dashboard settings. Navigate to the ***Tracker*** section and check the box for ***Page View Events***.

    <Note>It may take up to 6 hours for returning visitors to see the updated tracking code due to browser caching. Ensure your CDN respects our cache headers to prevent any unexpected delays.</Note>
  </Step>

  <Step title="Attach HTML Data Attributes">
    By including the `data-m:load` HTML attribute on any element on the page, you can automatically include additional metadata for each page visit. This attribute should be a key-value pair in the format `key=value` that will be sent with the event.

    The following example demonstrates how to attach custom properties on page load:

    ```html
    <!DOCTYPE html>
    <html>
    	<body data-m:load="theme=dark;subscription=paid">
    		<button data-m:load="logged_in=false">Log out</button>
    		<h1>Welcome to My Page</h1>
    	</body>
    </html>
    ```

    In this example, `{ "theme": "dark", "subscription": "paid", "logged_in": "true" }` will be attached to the page load event. Multiple properties can be separated by semi-colons.

    You can set these attributes statically or dynamically based on the user's state or any other relevant information.

    <Tip>Multiple properties can be separated by semi-colons.</Tip>
  </Step>

  <Step title="View Events">
    Once the tracking code is updated on your website, you can view the custom properties in the event list on your dashboard. Each event will include the custom properties attached to the page view, allowing you to filter and segment your data based on these properties.
  </Step>
</Steps>


# Page Views
Source: https://medama.mintlify.app/features/page-views



The page view tracking feature is the core of Medama that is enabled by default when you add the tracking code to your website. This feature allows you to track when a user loads a new page on your website and includes additional metadata about the visitor, such as the page URL, referrer URL, browser language, and more.

![Medama Analytics Homepage](https://mintlify.s3.us-west-1.amazonaws.com/medama/img/demo.png)

<Info>We recommend checking out our [Demo Dashboard](https://demo.medama.io) to fully understand what data is collected and how it is displayed.</Info>


# Introduction
Source: https://medama.mintlify.app/introduction



Medama Analytics is an open-source project dedicated to providing self-hostable, cookie-free website analytics. With a lightweight tracker of less than 1KB, it aims to offer useful analytics while prioritising user privacy.

![Medama Analytics Homepage](https://mintlify.s3.us-west-1.amazonaws.com/medama/img/demo.png)

## Features

* 📊 **Real-Time Analytics:** Monitor website performance and user interactions instantly.

* 🔒 **Privacy-Focused:** Lightweight tracker (\<1KB) without cookies, IP addresses, or additional identifiers, ensuring compliance with GDPR, PECR, and other regulations.

* 🧪 **Easy To Integrate:** [OpenAPI-based](/api-reference/introduction) server for effortless integration into personal or professional dashboards.

* 💼 **Self-Hostable:** Simple, single-binary setup with no external dependencies, capable of running on VMs with 256MB memory for most small websites.

## Quick Start

Designed for easy self-hosting and open-source by design, getting started is simpler than any other option in the market.

<CardGroup cols={2}>
  <Card title="Installation" icon="gear" href="/deployment/installation">
    Start self-hosting your own analytics instance.
  </Card>

  <Card title="Methodology" icon="pen-to-square" href="/methodology/overview">
    Learn how Medama Analytics collects and processes data.
  </Card>
</CardGroup>


# Bounce Rate
Source: https://medama.mintlify.app/methodology/bounce-rate



In our approach, we consider a bounce to occur when a unique visitor spends less than 5 seconds on a page, assuming both the `load` and `unload` events are successfully fired. While this method isn't flawless, it provides a practical representation given the limited data we collect compared to other solutions.

If the `unload` event isn't sent, we exclude the entire page view from bounce rate calculations. This is because, without the unload event, we cannot accurately measure the time spent on the page which will skew calculations.

<Tip>You can learn more about what are `load` and `unload` events [here](/methodology/metrics).</Tip>


# Location
Source: https://medama.mintlify.app/methodology/location



Traditional analytics tools often rely on IP addresses to determine a visitor's location, typically by downloading an IP geolocation database and querying it for each request. These databases must be updated regularly to remain accurate, as IPs are reassigned frequently.

To maintain user privacy, we avoid using IP addresses. Instead, we determine a visitor's country based on the browser's timezone. Each country has a specific timezone, and modern devices automatically set this based on the user's location. This approach provides an accurate representation of where visitors are coming from without relying on more invasive data sources.

<Note>Due to the nature of this method, we cannot determine the exact city or region a visitor is from. This is a trade-off we intentionally make to prioritise end user privacy.</Note>


# Metrics
Source: https://medama.mintlify.app/methodology/metrics



Our tracking script sends very few data points. This document outlines the metrics we collect and their usage.

## What We Don't Collect

To clarify, we do NOT use **cookies**, **IP addresses**, or any other identifiers to track individual users. This also applies to similar technologies like [local storage](https://en.wikipedia.org/wiki/Web_storage), [session cookies](https://en.wikipedia.org/wiki/HTTP_cookie#Session_cookie), [IP address hashing](https://dl.gi.de/items/939f8290-d554-4653-9129-d241475da55b), etc.

## Page Events

### Load Event

When a user loads a new page, the tracking script sends a `load` event to the server. This event includes the following data:

```json
{
	"b": "lxmc2mrt04wt1790jnjb",          // Beacon ID.
	"e": "load",                          // Event type.
	"u": "https://your-website.com/page", // Page URL.
	"r": "google.com",                    // Referrer URL.
	"p": false,                           // If the visitor is unique or not.
	"q": true,                            // If the visitor has visited this specific page before.
	"t": "Europe/London"                  // Timezone of the visitor.
}
```

The Beacon ID is a randomly generated identifier used to link the `load` and `unload` events together. This is generated per-page load and is not stored or used for any other purpose and cannot be used to identify a specific individual. For example, if you refresh your page, a new Beacon ID would be generated.

<Note>The timezone field is used to estimate the user's country without relying on an IP address. More details on this can be found [here](/methodology/location).</Note>

### Unload Event

When a user closes the tab or navigates away from the page, the tracking script sends an unload event to the server. This event includes the following data:

```json
{
	"b": "lxmc2mrt04wt1790jnjb", // Beacon ID.
	"e": "unload",               // Event type.
	"m": 1451                    // Time spent on page in milliseconds.
}
```

This event is primarily used to calculate the average time spent on a page and the bounce rate of the website.

### HTTP Headers

In addition to the event data, your browser sends information through HTTP headers, allowing us to infer more about the visitor:

| HTTP Header       | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `Accept-Language` | Languages used by the visitor's browser.              |
| `User-Agent`      | Browser, device, and operating system of the visitor. |

### Timestamps

We store timestamps of each event to record when an event occurred for the charts we display.

#### Data Processing

<Info>We split the events into `load` and `unload` in order to improve accuracy. The `unload` event is prone to failure as suddenly closing a browser tab or other factors can prevent the event from being properly sent. By merging the data received from both events, we can provide a more accurate representation of the user's behavior.</Info>

## Custom Properties

Users who choose to use our custom properties feature can send additional data points to the server.

### Data Event

This payload is sent using the `tagged-events` feature of your tracking script. The event includes the following data:

```json
{
	"b": "lxmc2mrt04wt1790jnjb", // Beacon ID.
	"e": "custom",               // Event type.
	"g": "yourwebsite.com", 	 // Group name of events, typically your hostname.
	"d": {...}                   // Custom data property object (nesting not supported).
}
```

The Beacon ID links the custom event to the page load and unload events, enabling page view filters to affect these events on your dashboard. The group name is currently unused but may be utilised in the future for event grouping.


# Overview
Source: https://medama.mintlify.app/methodology/overview

Privacy-focused by default, transparency by design.

Privacy and analytics are conflicting statements. Therefore, it is important to maintain a strict balance between the two and ensure data is never collected more than absolutely necessary as a core principle.

To understand our approach, we broke down **how** we collect data and **what** we collect in the following documents.

<CardGroup cols={2}>
  <Card title="Metrics" icon="pen-to-square" href="/methodology/metrics">
    What we collect and what we don't.
  </Card>

  <Card title="Unique Visitors" icon="user-shield" href="/methodology/unique-visitors">
    How we determine unique visitors without using cookies or IPs.
  </Card>

  <Card title="Location" icon="globe" href="/methodology/location">
    Understanding user location without relying on IP addresses.
  </Card>

  <Card title="Bounce Rate" icon="arrow-trend-up" href="/methodology/bounce-rate">
    Defining what bounce rate is and how it is calculated.
  </Card>
</CardGroup>


# Unique Visitors
Source: https://medama.mintlify.app/methodology/unique-visitors



The traditional approach for identifying unique visitors involves using cookies or IP addresses that often violate privacy laws due to their ability to individually identify users. A newer alternative employed by more privacy-oriented solutions involve hashing IP addresses for pseudonymisation. However, this can also fall into a privacy grey area and can be compromised according to some [academic papers](https://dl.gi.de/items/939f8290-d554-4653-9129-d241475da55b).

To adhere strictly to privacy regulations, we use a browser cache-based approach to track unique visitors without personal identifiers. In simpler terms, if a visitor has visited the website before, their browser would have cached the tracking script's request. If they have not visited the website before, the tracking script's request would not have been cached yet. This allows us to differentiate between new and returning visitors without using cookies or IP addresses.

This approach does not allow us to identify individual users and therefore abides by existing privacy regulations.

## Technical Explanation

Here's a detailed explanation of how this method works:

* **Initial Request**: When a visitor accesses the site, the tracking script sends a request to the API server.
  * **Unique Visitor**: If the user has not visited the site before, they will ping the server without a cached `If-Modified-Since` timestamp. The server then responds with a `Last-Modified` header set to the current date.
  * **Returning Visitor**: If the user has visited the site before, their browser will include an `If-Modified-Since` header with the date of the last `Last-Modified` response when pinging the server. The server can then recognise that the visitor has visited the site before.

The `Last-Modified` timestamp is reset every day to ensure that visitors are counted as unique each new day.

By using the `Last-Modified` and `If-Modified-Since` cache headers, we can determine if the visitor has visited the website before. This approach is simple, efficient, and preserves the anonymity of the visitor.