## 1. Project Overview & Quickstart (skyzh/LICENSE) # LICENSE Open-source repository skyzh/LICENSE ### Repository Details - **Repository:** [skyzh/LICENSE](https://github.com/skyzh/LICENSE) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (skyzh/website) ## File: README.md # umami.is This is the repository of the [Umami](https://umami.is) website built using [Next.js](https://nextjs.org/). ## About Umami is a simple, easy to use, self-hosted web analytics solution. The goal is to provide you with a friendlier, privacy-focused alternative to Google Analytics and a free, open-sourced alternative to paid solutions. Umami collects only the metrics you care about and everything fits on a single page. ## Starting the project 👨‍💻 ```sh # using npm npm install npm run dev ``` ```sh # using yarn yarn yarn dev ``` ## Contributions Would be happy to take contributions to improve the website. Help is needed especially in the [**Guides**](https://umami.is/docs/hosting) section. If you know how to configure or deploy Umami in different environments, please share your knowledge. --- ## File: content/v1/about.mdx # About ## What is Umami? Umami is an open source, privacy-focused alternative to Google Analytics. Umami provides you with a powerful web analytics solution that does not violate the privacy of your users. Additionally, when you self-host Umami you are in complete control of your data. --- ## File: content/v1/add-a-website.mdx # Add a website Log into Umami and click on **Settings** in the header. Then navigate to **Websites** and click on the **Add website** button. Fill out the form details and click the **Save** button. The **Name** field can be whatever you want. Usually it's the same as the domain name. The **Domain** field is the actual domain of your website. It is used to filter out your own website from the list of referrers in your metrics. The **Enable share URL** checkbox means you want to share your website stats via a unique URL. --- ## File: content/v1/add-an-account.mdx # Add an account Umami allows you to create separate accounts so that you can host data for friends or clients. Log into Umami as the administrator and click on **Settings** in the header. Then navigate to **Accounts** and click on the **Add account** button. Fill out the form details and click the **Save** button. The new account will have its own dashboard and websites separate from the **admin** account. Only the **admin** is able to create, modify and delete accounts. The new account will not have access to the **Accounts** tab. --- ## File: content/v1/api.mdx # API Umami allows you to pull data directly by calling the API endpoints. The endpoints are available at `http:///api`. All data is returned as JSON. Any operation you can do through the Umami admin panel is available in the API, but it might not yet be documented. ## Authentication ## `POST /api/auth/login` First you need to get a _token_ in order to make API requests. You need to make a `POST` request to the `/api/auth/login` endpoint with the following data: ```json { "username": "your-username", "password": "your-password" } ``` If successful you should get a response like the following: ```json { "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A" } ``` Save the token value and send an `Authorization` header with all your data requests with the value `Bearer `. Your request header should look something like this: ```http request Authorization: Bearer eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A ``` For example, with `curl` it would look like this: ```shell curl https://yoursever/api/websites -H "Accept: application/json" -H "Authorization: Bearer " ``` Prior to v1.26.0, Umami used cookies. If using an older version, you would do the following instead: Save the token value and pass it as a _cookie_ with all your data requests. The cookie name is `umami.auth`. Your request header should look something like this: ``` Cookie: umami.auth=eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A ``` ## Websites Operations around Websites that Umami is tracking. ## `POST /api/websites` Creates a website. **Parameters** - `domain`: (string) The full domain of the tracked website - `name`: (string) The name of the website in Umami - `enable_share_url`: (boolean) Enables a public URL for the stats for this Website - `public`: (boolean) false by default **Sample response** ``` { id: 4, websiteUuid: "51f73213-3f01-4343-a135-25496a3ffd31", userId: 2, name: "Umami", domain: "umami.is", shareId: "8PWex1pa", createdAt: "2021-07-26T17:17:52.846Z" } ``` ## `GET /api/websites` Returns all tracked websites. **Parameters** None **Sample response** ``` [ { id: 4, websiteUuid: "51f73213-3f01-4343-a135-25496a3ffd31", userId: 2, name: "Umami", domain: "umami.is", shareId: "8PWex1pa", createdAt: "2021-07-26T17:17:52.846Z" }, { ... } ] ``` Prior to v1.39 some fields had a different name. If using an old version, use `website_id` instead of `id`, and rewrite the other fields in snake case (for example `share_id` instead of `shareId`). ## Getting stats There are several endpoints your can call to get stats for your website. All the stats endpoints require sending a `GET` request with the `Bearer ` (post v1.26.0) or `umami.auth` authentication cookie. ## `GET /api/websites/{websiteUuid}/stats` Gets summarized website statistics. **Query Parameters** - `start_at`: Timestamp (in ms) of starting date - `end_at`: Timestamp (in ms) of end date **Sample example** GET (with Authorization header) from url : `https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/stats?start_at=1656679719687&end_at=1656766119687` ``` { pageviews: { value: 5, change: 5 }, uniques: { value: 1, change: 1 }, bounces: { value: 0, change: 0 }, totaltime: { value: 4, change: 4 } } ``` - `pageviews`: Pages hits - `uniques`: Number of unique visitor - `bounces`: Number of returning visitor - `totaltime` : Time spent on the website ## `GET /api/websites/{websiteUuid}/pageviews` Gets pageviews within a given time range. **Parameters** - `start_at`: Timestamp (in ms) of starting date - `end_at`: Timestamp (in ms) of end date - `unit`: Time unit (year | month | hour | day) - `tz`: Timezone (ex. America/Los_Angeles) **Sample response** ``` { pageviews: [ {t: "2020-04-20 01:00:00", y: 3}, {t: "2020-04-20 02:00:00", y: 7} ], sessions: [ {t: "2020-04-20 01:00:00", y: 2}, {t: "2020-04-20 02:00:00", y: 4} ] } ``` ## `GET /api/websites/{websiteUuid}/events` Gets events within a given time range. **Parameters** - `start_at`: Timestamp (in ms) of starting date - `end_at`: Timestamp (in ms) of end date - `unit`: Time unit (year | month | hour | day) - `tz`: Timezone (ex. America/Los_Angeles) **Sample response** ``` [ {x: "download-button", t: "2020-04-20 02:00:00", y: 2}, {x: "signup-button", t: "2020-04-20 02:00:00", y: 1} ] ``` ## `GET /api/websites/{websiteUuid}/metrics` Gets metrics for a given time range. **Parameters** - `start_at`: Timestamp (in ms) of starting date - `end_at`: Timestamp (in ms) of end date - `type`: Metrics type (url | referrer | browser | os | device | country | event) **Sample response** ``` [ {x: "/", y: 46} {x: "/docs", y: 17} {x: "/download", y: 14} ] ``` ## Sending stats ## `POST /api/collect` To register a `pageview` or `event`, you need to send a `POST` to `/api/collect` with the following data: ``` { payload: { website: "your-website-id", url: "/", referrer: "", hostname: "your-hostname", language: "en-US", screen: "1920x1080", }, type: "pageview" } ``` For events, from v1.37 onwards, you would send: ``` { payload: { website: "your-website-id", url: "/", event_name: "click-signup-button", hostname: "your-hostname", language: "en-US", screen: "1920x1080" }, type: "event" } ``` Prior to v1.37, the `event_name` was separated into two different fields: `event_type` and `event_value`: ``` { payload: { website: "your-website-id", url: "/", event_type: "click", event_value: "signup-button", hostname: "your-hostname", language: "en-US", screen: "1920x1080" }, type: "event" } ``` Note, for `/api/collect` requests you do not need to send an authentication token. Also, you need to send a proper `User-Agent` HTTP header or your request won't be registered. --- ## File: content/v1/collect-data.mdx # Collect data Once you've added your website. Click on the **Get tracking code** button. From the form that pops up, copy the code and insert it into the `` section of your website. Then visit your website and data should immediately appear in your Umami dashboard. ### Troubleshooting - If your site was built with [Next.js](https://nextjs.org/), Insert the above code block using the [next/script](https://nextjs.org/docs/basic-features/script#usage) component within your `index.js/tsx` file. --- ## File: content/v1/enable-share-url.mdx # Enable share URL By default a website's metrics can only be seen by the account owner. But you can choose to make the stats available through a uniquely generated URL. Log into Umami and click on **Settings** in the header. Then navigate to **Websites** and click on the **Edit** button next to your website. Check the **Enable share URL** checkbox and click **Save**. Then click the **Share URL** button next to your website. The form that pops up will show you the URL. --- ## File: content/v1/environment-variables.mdx # Environment variables You can configure Umami with the use of environment variables. They go into the same `.env` file as your `DATABASE_URL`. --- ## Runtime variables Runtime variables are recognized when Umami is running. You can set your environment variables prior to starting the application. ### DATABASE_URL = <connection string> Connection string for your database. This is the only required variable. ### IGNORE_IP = <ip addresses> You can provide a comma-delimited list of IP address to exclude from data collection. ### IGNORE_HOSTNAME = <hostname> This will do a DNS lookup on a hostname and the resulting IP address will be ignored. This can be a comma delimited list of hostnames. ### FORCE_SSL = 1 This will redirect all requests from `http` to `https` in the Umami application. Note, this does not apply to the tracking script. ### LOG_QUERY = 1 If you are running in development mode, this will log database queries to the console for debugging. ### HOSTNAME = <hostname> ### PORT = <port number> If you are running on an environment which requires you to bind to a specific hostname or port, such as Heroku, you can add these variables and start your app with `npm run start-env` instead of `npm start`. ### CLIENT_IP_HEADER = <header name> HTTP header to check for the client's IP address. This is useful when you're behind a proxy that uses non-standard headers. ### REMOVE_TRAILING_SLASH = 1 Removes the trailing slash from all incoming urls. ### TRACKER_SCRIPT_NAME = <script name> Allows you to assign a custom name to the tracker script different from the default `umami`. This is to help you avoid some ad-blockers. Note: If you update this, be sure to update the tracking code on your website to the new name. ### COLLECT_API_ENDPOINT = /api/x Allows you to send metrics to a location different than the default `/api/collect`. This is to help you avoid some ad-blockers. ### DISABLE_UPDATES = 1 Disables the check for new versions of Umami. ### DISABLE_LOGIN = 1 Disables the login page for the application. ### DISABLE_TELEMETRY = 1 Umami collects completely anonymous telemetry data in order help improve the application. You can choose to disable this if you don't want to participate. --- ## Build time variables Build time variables are only recognized during the build process. This also includes building custom Docker images. You need to set your environment variables prior to building the application. ### BASE_PATH = <path> If you want to host Umami under a subdirectory. You may need to update your reverse proxy settings to correctly handle the BASE_PATH prefix. ### DATABASE_TYPE = <postgresql | mysql> The type of DB to be used. This is only required for the Docker build. --- ## File: content/v1/faq.mdx # Frequently asked questions ### 1. Is Umami GDPR compliant? Yes, Umami does not collect any personally identifiable information and anonymizes all data collected. Users cannot be identified and are never tracked across websites. ### 2. Do I need to display a cookie notice to users? No, Umami does not use any cookies in the tracking code. ### 3. Does Umami work on a single page application (SPA)? Yes, Umami works seamlessly between SPAs and normal websites. ### 4. Can Umami record events such as button clicks? Yes, please see [Track Events](/docs/track-events) under **Getting Started**. ### 5. Where can I go for help if I have problems or want to request a feature? For general discussions and troubleshooting you can use the [discussions](https://github.com/umami-software/umami/discussions) on Github. For bug reports and feature requests, please file an [issue](https://github.com/umami-software/umami/issues) on GitHub. For the most fun, join the Umami community on [Discord](https://discord.gg/4dz4zcXYrQ)! --- ## File: content/v1/features.mdx # Statements ## Simple analytics Umami measures just the important metrics that you care about: pageviews, devices used, and where your visitors are coming from. Everything is displayed on a single, easy to browse page. ## Unlimited websites Umami is able to track an unlimited number of websites from a single installation. You can even track subdomains and individual URLs. ## Bypass ad-blockers Umami is hosted by you under your own domain so you can reliably avoid ad-blockers unlike Google Analytics. ## Light-weight The tracking script is tiny (only 2KB) and supports legacy browsers like IE. ## Multiple accounts Umami can be used to host data for friends or clients. Just create a separate account and they can start tracking their own websites on their own dashboard. ## Share data If you want to share your stats publicly, you can do so with a uniquely generated URL. ## Mobile-friendly The Umami interface has been optimized for mobile so you can view your stats from anywhere. ## Data ownership Since Umami is self-hosted you own all the data. No need to hand your data to a third party to be exploited. ## Privacy-focused Umami does not collect any personally identifiable information and anonymizes all data collected. ## Open-source Umami is open-source and licensed under the MIT license. The source code is available on [Github](https://github.com/umami-software/umami).