### Run Jekyll Server Locally
Source: https://github.com/simpleanalytics/docs/blob/master/README.md
This command starts the Jekyll development server on your local machine. It allows you to preview the documentation website before deployment. Ensure you have Ruby and Bundler installed.
```bash
bundle exec jekyll serve
```
--------------------------------
### Expected Output for Proxied Simple Analytics Embed Script
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This JavaScript snippet shows the expected starting content of the `proxy.js` file when accessed via your configured proxy, confirming that the proxy is correctly serving the Simple Analytics embed script.
```js
/* Simple Analytics - Privacy friendly analytics ... */
```
--------------------------------
### Example Rendered HTML Output with Simple Analytics
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_django.md
Illustrative HTML showing the approximate output generated by the Simple Analytics template tags, including the analytics script and the noscript fallback image, as seen by the browser.
```html
example.com
...
...
```
--------------------------------
### Simple Analytics Embed Script with Optional Noscript Fallback
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This HTML example provides the Simple Analytics embed script along with an optional `` tag for environments where JavaScript is disabled. It's generally not recommended due to potential bot traffic, but demonstrates how to include a fallback image request via the proxy.
```html
```
--------------------------------
### SwiftUI Pageview Tracking Example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Demonstrates how to track pageviews in a SwiftUI application by placing the track call within the .onAppear modifier of a View. This ensures the pageview is recorded when the view becomes visible.
```Swift
import SwiftUI
import SimpleAnalytics
struct ContentView: View {
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, world!")
}
.padding()
.onAppear {
SimpleAnalytics.shared.track(path: ["example"])
}
}
}
```
--------------------------------
### Install Simple Analytics Docusaurus Plugin
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_docusaurus.md
Run this command to install the Simple Analytics plugin for Docusaurus using npm. The --save flag adds it to your project's dependencies.
```bash
npm install docusaurus-plugin-simple-analytics --save
```
--------------------------------
### Install Gatsby Simple Analytics Plugin
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_gatsby.md
Command to install the `gatsby-plugin-simple-analytics` package as a development dependency using npm.
```bash
npm install gatsby-plugin-simple-analytics --save-dev
```
--------------------------------
### Install Analytics Library and Simple Analytics Plugin via npm
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/05_analytics.md
This command installs the core `analytics` library and the `@analytics/simple-analytics` plugin using npm. These packages are essential for integrating Simple Analytics into your application.
```bash
npm install analytics @analytics/simple-analytics
```
--------------------------------
### Install Simple Analytics Python Package
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_django.md
Command to install the `simpleanalytics` Python package using pip, which provides the necessary integration functionalities for Django projects.
```bash
pip install simpleanalytics
```
--------------------------------
### Install Ruby gems using Bundler
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_rubyonrails.md
After adding new gems to your `Gemfile`, execute `bundle install` in your terminal. This command resolves and installs all specified gem dependencies for your Ruby on Rails project.
```Bash
bundle install
```
--------------------------------
### Simple Analytics Installation Script
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/01_introduction.md
This script asynchronously loads the Simple Analytics tracking library. It should ideally be placed in the `` tag, but can be moved to the `` if necessary. For custom domains, replace the default `simpleanalyticscdn.com` with your domain.
```html
```
--------------------------------
### UIKit Pageview Tracking Example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Illustrates how to track pageviews in a UIKit application by placing the track call within the viewDidAppear() method of a UIViewController. This ensures the pageview is recorded after the view has appeared on screen.
```Swift
import UIKit
import SimpleAnalytics
class ExampleViewController: UITableViewController {
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
SimpleAnalytics.shared.track(path: ["example"])
}
}
```
--------------------------------
### Initialize Simple Analytics Instance with Hostname
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Creates a new instance of the SimpleAnalytics class, providing the hostname of your Simple Analytics website. This hostname is crucial for associating analytics data with your account.
```Swift
let simpleAnalytics = SimpleAnalytics(hostname: "mobileapp.yourdomain.com")
```
--------------------------------
### Install Gridsome Simple Analytics Plugin via npm
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_gridsome.md
This command installs the `gridsome-plugin-simple-analytics` package using npm, making it available for use in your Gridsome project. It's the first step to integrate Simple Analytics.
```bash
npm install gridsome-plugin-simple-analytics
```
--------------------------------
### Integrate Simple Analytics Template Tags in Django HTML
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_django.md
Example HTML structure demonstrating how to load `simpleanalytics_tags` and use `simpleanalytics_sync` for script inclusion and `simpleanalytics_noscript_block` for fallback in a Django template.
```html
{% load static simpleanalytics_tags %}
{% block page_title %}{{ site.name }}{% endblock %}
... {% simpleanalytics_sync %} ...
{% simpleanalytics_noscript_block %}
```
--------------------------------
### Simple Analytics Plugin: Custom Setting Example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_create-plugin.md
Demonstrates how custom settings can be passed to the Simple Analytics script, allowing for future-proof integration of new features like 'collect-dark-mode'.
```HTML
```
--------------------------------
### Install Simple Analytics Vue.js Package
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vue.md
Command to install the Simple Analytics Vue.js package using npm.
```bash
npm install simple-analytics-vue
```
--------------------------------
### Valid URL parameter examples with escaping
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/03_how-to-use-url-params.md
Collection of valid URL examples demonstrating the use of `ref` parameters, including cases with URL-encoded special characters and an empty parameter, showcasing acceptable formats for Simple Analytics.
```URL
https://example.com/?ref=email-button
https://example.com/
https://example.com/?ref=android%3A%2F%2Fcom.example.app%2Fpath
https://example.com/?ref=exister%2C%20avoir%20une%20r%C3%A9alit%C3%A9
```
--------------------------------
### Export Daily Pageview Data with cURL
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/20_export-data-points.md
Provides a cURL command example to export daily pageview data from Simple Analytics. This example demonstrates how to use API authentication headers (`User-Id`, `Api-Key`) and specify query parameters like `version`, `format`, `hostname`, `start`, `end`, `fields`, and `type` for data retrieval.
```bash
curl "https://simpleanalytics.com/api/export/datapoints?version={{ site.api_version }}&format=csv&hostname=simpleanalytics.com&start={{ "now" | date: '%s' | minus: 2592000 | date: '%Y-%m-%d' }}&end={{ "now" | date: '%Y-%m-%d' }}&robots=false&timezone=Europe%2FAmsterdam&fields=added_iso,path&type=pageviews" \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: text/csv'
```
--------------------------------
### Manually install simple_analytics_rails Ruby gem
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_rubyonrails.md
For direct installation without Bundler, use the `gem install` command. This installs the `simple_analytics_rails` gem globally or within your current Ruby environment, making it available for use.
```Bash
gem install simple_analytics_rails
```
--------------------------------
### Create Shared Simple Analytics Instance Extension
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Defines a static shared instance of SimpleAnalytics using an extension, allowing for easy access throughout the application without repeated initialization. This promotes a singleton pattern for the analytics client.
```Swift
import SimpleAnalytics
extension SimpleAnalytics {
static let shared: SimpleAnalytics = SimpleAnalytics(hostname: "mobileapp.yourdomain.com")
}
```
--------------------------------
### API Reference: GET /api/websites
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/35_admin.md
Documentation for the endpoint to retrieve all websites. This endpoint is available for all plans and returns a list of websites associated with the authenticated user.
```APIDOC
Endpoint: GET https://simpleanalytics.com/api/websites
Description: Retrieves a list of all websites for the authenticated user.
Authentication: Required (Api-Key, User-Id)
Headers:
Content-Type: application/json
Api-Key: Your Simple Analytics API Key
User-Id: Your Simple Analytics User ID
Response: Array of website objects
```
--------------------------------
### Basic Configuration for Gridsome Simple Analytics Plugin
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_gridsome.md
This JavaScript configuration snippet shows how to enable the `gridsome-plugin-simple-analytics` in your Gridsome project's `gridsome.config.js` file. This minimal setup activates basic analytics tracking without custom options.
```js
module.exports = {
plugins: [
{
use: "gridsome-plugin-simple-analytics",
},
],
};
```
--------------------------------
### Configure Advanced Simple Analytics Options in VuePress
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vuepress.md
Customize the Simple Analytics plugin behavior by providing an options object in your VuePress config.js. This example demonstrates setting a customDomain for bypassing ad-blockers, defining an eventsGlobal object for tracking, and enabling skipDnt to collect data from DNT users.
```javascript
module.exports = {
plugins: [
[
"vuepress-plugin-simple-analytics",
{
customDomain: "data.example.com", // You custom domain
eventsGlobal: "sa", // The global events object for sa("click_button")
skipDnt: true // When set to true you track the DNT users
}
]
]
};
```
--------------------------------
### Original User-Agent String Example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/15_metrics.md
This snippet presents an example of an original user-agent string. Browsers and devices transmit this string to websites to identify themselves, providing information about the operating system, browser, and device type.
```Text
Mozilla/5.0 (iPad; U; CPU OS 3_2_1) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B40598
```
--------------------------------
### Install VuePress Simple Analytics Plugin via npm
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vuepress.md
Use npm to install the vuepress-plugin-simple-analytics package as a development dependency for your VuePress project. This command adds the necessary plugin files to your project.
```bash
npm install vuepress-plugin-simple-analytics --save-dev
```
--------------------------------
### Simple Analytics Inline Events Script Installation
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/00_inline-events.md
Instructions for including the Simple Analytics main tracker and the inline events helper script on your web page, typically before the closing tag.
```html
```
--------------------------------
### Initialize Analytics Library with Simple Analytics Plugin in JavaScript
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/05_analytics.md
This JavaScript code demonstrates how to import and initialize the `analytics` library with the `simpleAnalyticsPlugin`. Once initialized, it automatically tracks page views, providing a seamless integration for Simple Analytics.
```js
/* src/analytics.js */
import Analytics from "analytics";
import simpleAnalyticsPlugin from "@analytics/simple-analytics";
const analytics = Analytics({
app: "awesome-app",
plugins: [
// Load simple analytics! 🎉
simpleAnalyticsPlugin()
]
});
/* All page views are now tracked by simple analytics */
```
--------------------------------
### Simple Analytics Stats API Endpoint Example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/20_chartbrew.md
This is an example of the full URL used to fetch statistical data, specifically histogram data, from the Simple Analytics API. It includes versioning and specifies the fields to retrieve.
```APIDOC
https://simpleanalytics.com/simpleanalytics.com.json?version=4&fields=histogram
```
--------------------------------
### Configure Netlify Redirects for Simple Analytics Proxy
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This Netlify _redirects configuration sets up proxy rules for Simple Analytics, directing proxy.js, auto-events.js, and the main analytics queue through your Netlify site. This helps mask visitor IP addresses from external services. Ensure you replace example.com with your actual domain and adjust the /simple path if necessary.
```netlify
/proxy.js https://simpleanalyticsexternal.com/proxy.js?hostname=example.com&path=/simple 200
/auto-events.js https://scripts.simpleanalyticscdn.com/auto-events.js 200
/simple/* https://queue.simpleanalyticscdn.com/:splat 200
```
--------------------------------
### Install Simple Analytics Vue package for Nuxt 3
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_nuxt.md
Command to install the `simple-analytics-vue` package as a development dependency for Nuxt 3 projects.
```bash
npm install simple-analytics-vue --save-dev
```
--------------------------------
### Configure Caddy for Simple Analytics Proxy
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This Caddyfile configuration establishes a reverse proxy for Simple Analytics, routing traffic and handling proxy.js and auto-events.js requests. It specifically strips the /simple prefix and prevents the X-Forwarded-For header from being sent, enhancing privacy. Update example.com to your domain.
```caddy
example.com {
handle /simple/* {
uri strip_prefix /simple
reverse_proxy https://queue.simpleanalyticscdn.com {
header_up X-Caddy-Proxy "true"
header_up -X-Forwarded-For
}
}
handle /proxy.js {
rewrite * /proxy.js?{query}&hostname=example.com&path=/simple
reverse_proxy https://simpleanalyticsexternal.com {
header_up -X-Forwarded-For
}
}
handle /auto-events.js {
rewrite * /auto-events.js
reverse_proxy https://scripts.simpleanalyticscdn.com {
header_up -X-Forwarded-For
}
}
}
```
--------------------------------
### Add Simple Analytics Plugin to Docusaurus Configuration
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_docusaurus.md
After installation, add the 'docusaurus-plugin-simple-analytics' to the 'plugins' array in your 'docusaurus.config.js' file. This activates the plugin for your Docusaurus site.
```js
plugins: [
...
['docusaurus-plugin-simple-analytics', {}],
...
],
```
--------------------------------
### Install Simple Analytics Vue package for Nuxt 2
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_nuxt.md
Command to install a specific version of the `simple-analytics-vue` package as a development dependency for Nuxt 2 projects.
```bash
npm install simple-analytics-vue@2.x --save-dev
```
--------------------------------
### Initialize Simple Analytics with Custom Domain
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vue.md
Configures Simple Analytics to use a custom domain, which can help bypass ad blockers.
```js
Vue.use(SimpleAnalytics, { domain: "api.example.com" });
```
--------------------------------
### Import Simple Analytics Swift Library
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Imports the Simple Analytics module into your Swift file, making its classes and functions available for use in your application.
```Swift
import SimpleAnalytics
```
--------------------------------
### Combined Simple Analytics Proxy Embed and Automated Events Scripts
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This HTML block shows the complete set of script tags required to integrate Simple Analytics with both the proxy and automated events features, loading all resources from your own proxied domain.
```html
```
--------------------------------
### Configure Simple Analytics in Django INSTALLED_APPS
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_django.md
Add `simpleanalytics` to the `INSTALLED_APPS` list in your Django project's settings file to enable the application's functionalities and make its template tags available.
```python
INSTALLED_APPS = [
...,
simpleanalytics,
]
```
--------------------------------
### HTML script tag for Simple Analytics system plugin settings
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_create-plugin.md
Example of how settings are passed to the Simple Analytics script tag as data attributes for system plugins. These settings are typically managed and applied via a plugin's user interface.
```html
```
--------------------------------
### Initial HTML Structure for Link
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/20-sa-link-event.md
Demonstrates a basic HTML paragraph containing a hyperlink, serving as the starting point before applying custom event tracking.
```html
This is a link .
```
--------------------------------
### Create Simple Analytics Plugin for Nuxt.js
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vue.md
Defines a Nuxt.js plugin file (`simple-analytics.js`) to import and initialize Simple Analytics, similar to a standard Vue application.
```js
// ~/plugins/simple-analytics.js
import SimpleAnalytics from "simple-analytics-vue";
import Vue from "vue";
Vue.use(SimpleAnalytics, { skip: process.env.NODE_ENV !== "production" });
```
--------------------------------
### Configure Gatsby Simple Analytics Plugin
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_gatsby.md
Basic configuration for `gatsby-plugin-simple-analytics` in `gatsby-config.js` to enable page view tracking.
```javascript
plugins: [
{
resolve: "gatsby-plugin-simple-analytics",
options: {
trackPageViews: true,
},
},
]
```
--------------------------------
### Initialize Simple Analytics with Conditional Skip Logic
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vue.md
Initializes Simple Analytics with a `skip` option that accepts a function or promise, allowing dynamic control over when page views are skipped.
```js
import auth from "lib/auth";
Vue.use(SimpleAnalytics, { skip: auth.isAdminPromise });
```
--------------------------------
### Configure NGINX for Simple Analytics Proxy
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This NGINX configuration sets up a reverse proxy for Simple Analytics, routing traffic through your server to protect visitor IP addresses. It includes rules for the main analytics queue, proxy.js, and auto-events.js, ensuring proper header forwarding and caching. Remember to adjust example.com and the /simple path as needed.
```nginx
location ^~ /simple/ {
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Proto-Version $http2;
proxy_set_header Host $http_host;
proxy_set_header X-NginX-Proxy true;
proxy_set_header Connection "";
proxy_pass_request_headers on;
proxy_pass https://queue.simpleanalyticscdn.com/;
}
location = /proxy.js {
expires 7d;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
proxy_pass https://simpleanalyticsexternal.com/proxy.js?hostname=example.com&path=/simple;
}
location = /auto-events.js {
expires 7d;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
proxy_pass https://scripts.simpleanalyticscdn.com/auto-events.js;
}
```
--------------------------------
### Import and Initialize Simple Analytics in Vue.js
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vue.md
Imports the Simple Analytics Vue plugin and initializes it with Vue.js, skipping page views in development environments.
```js
import SimpleAnalytics from "simple-analytics-vue";
import Vue from "vue";
Vue.use(SimpleAnalytics, { skip: process.env.NODE_ENV !== "production" });
```
--------------------------------
### Authenticate Simple Analytics API with API Key using cURL
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/10_authenticate.md
This cURL example demonstrates how to authenticate with the Simple Analytics API using an `Api-Key` header. It fetches data for a specific domain, replacing example values with your own API key to test its functionality.
```bash
curl "https://simpleanalytics.com/example.com.json?version={{ site.api_version }}&fields=histogram" \
-H 'Content-Type: application/json' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
```
--------------------------------
### Create Simple Analytics plugin file for Nuxt 2
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_nuxt.md
Create a client-side plugin file for Nuxt 2 to integrate Simple Analytics, configured to skip development visits.
```js
// ~/plugins/simple-analytics.js
import SimpleAnalytics from "simple-analytics-vue";
import Vue from "vue";
Vue.use(SimpleAnalytics, { skip: process.env.NODE_ENV !== "production" });
```
--------------------------------
### Example Output of CloudQuery Sync
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/55_cloudquery.md
Illustrates the expected terminal output after a successful CloudQuery sync operation, showing messages for loading specs, migration completion, and sync completion with resource counts and total time taken.
```text
➜ playground cloudquery sync simpleanalytics.yml bigquery.yml
Loading spec(s) from simpleanalytics.yml
Starting migration with 2 tables for: simpleanalytics (v1.0.0) -> [bigquery (v2.1.3)]
Migration completed successfully.
Starting sync for: simpleanalytics (v1.0.0) -> [bigquery (v2.1.3)]
Sync completed successfully. Resources: 105666, Errors: 0, Panics: 0, Time: 2m 10s
```
--------------------------------
### Safely Trigger Event with Callback, Checking `sa_loaded` and Do Not Track (JavaScript)
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/01_introduction.md
Provides a robust example of triggering an `sa_event` with a callback. It includes checks for `window.sa_loaded` to ensure the Simple Analytics script is ready and also checks for 'Do Not Track' settings, skipping the event if DNT is active or `sa_loaded` is not available.
```js
function callback() {
window.location.href = "https://example.com/?affiliate=...";
}
/* Check for DoNotTrack visitors */
var dntActive = parseInt(navigator.msDoNotTrack || window.doNotTrack || navigator.doNotTrack, 10) === 1;
/* Check for sa_loaded boolean */
if (window.sa_loaded && !dntActive) sa_event("outbound_link_to_affiliate", callback);
else callback();
```
--------------------------------
### Example URL with UTM Parameters
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/15_metrics.md
This snippet illustrates a typical URL augmented with UTM parameters. These parameters are used by analytics tools, including Simple Analytics, to provide detailed insights into marketing campaign performance and traffic sources.
```Text
https://example.com/landing-page?utm_source=company-x&utm_medium=newsletter&utm_campaign=march
```
--------------------------------
### Example of URL with UTM codes
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/03_how-to-use-url-params.md
Demonstrates a URL incorporating multiple UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`) for detailed tracking in Simple Analytics, along with a custom parameter `project-id`.
```URL
https://example.com/landing-page?utm_source=company-x&utm_medium=newsletter&utm_campaign=march_01&project-id=123
```
--------------------------------
### Example API Request with Date Placeholders
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/50_helpers.md
This URL demonstrates how to query the Simple Analytics API using date placeholders like 'yesterday' and 'today' along with a specified timezone. It retrieves histogram data for a given domain, showing how to construct a basic API call.
```HTTP
https://simpleanalytics.com/simpleanalytics.com.json?version={{ site.api_version }}&fields=histogram&start=yesterday&end=today&timezone=UTC
```
--------------------------------
### Track Basic Pageview in Swift
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Records a pageview event in Simple Analytics for a specific path within the application. This is typically used to track screen views.
```Swift
SimpleAnalytics.shared.track(path: ["list"])
```
--------------------------------
### Add a new website using cURL
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/35_admin.md
Example cURL command to add a new website to the Simple Analytics account via a POST request. This operation requires a Business or Enterprise plan and includes parameters for hostname, public status, and timezone.
```bash
curl -X "POST" "http://localhost:3000/api/websites/add" \
-H 'Content-Type: application/json' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
-d $'{
"public": false,
"hostname": "example.com",
"timezone": "Europe/Amsterdam"
}'
```
--------------------------------
### Enable Simple Analytics Plugin in VuePress config.js
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_vuepress.md
Add the vuepress-plugin-simple-analytics to the plugins array in your .vuepress/config.js file. This step activates the plugin within your VuePress application.
```javascript
module.exports = {
plugins: ["vuepress-plugin-simple-analytics"],
};
```
--------------------------------
### Metadata key sanitization example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/15_metadata.md
Demonstrates how non-alphanumeric characters in metadata keys are replaced with underscores and trimmed, showing the resulting sanitized key.
```js
sa_event("click_signup", { "$%!k_e___y__": "value" });
```
--------------------------------
### Basic URL parameter for custom referrer
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/03_how-to-use-url-params.md
Example of using the `ref` URL parameter to set a custom referrer for Simple Analytics, overriding the browser's default referrer.
```URL
https://example.com/landing-page?ref=email
```
--------------------------------
### Retrieve all websites using cURL
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/35_admin.md
Demonstrates how to use cURL to make a GET request to the Simple Analytics API to list all websites associated with the authenticated user. Requires API Key and User ID for authentication.
```bash
curl "https://simpleanalytics.com/api/websites" \
-H 'Content-Type: application/json' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000'
```
--------------------------------
### Track Event with Optional Path in Swift
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Records a custom event along with an optional path, providing additional context about where the event occurred within the application's navigation flow.
```Swift
SimpleAnalytics.shared.track(event: "logged in", path: ["login", "social"])
```
--------------------------------
### Example URL with UTM Tracking Parameters
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/10_what_we_collect.md
This snippet illustrates the structure of a URL augmented with UTM parameters. These parameters are used by Simple Analytics to track campaign source, medium, and other details, providing insights into visitor acquisition.
```URL
https://example.com/landing-page?utm_source=company-x&utm_medium=newsletter&utm_campaign=march
```
--------------------------------
### Configure Gatsby Simple Analytics Plugin with Custom Domain
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_gatsby.md
Advanced configuration for `gatsby-plugin-simple-analytics` in `gatsby-config.js` to use a custom domain, enable event tracking, and ignore specific pages.
```javascript
plugins: [
{
resolve: "gatsby-plugin-simple-analytics",
options: {
domain: "custom.example.com",
eventsGlobal: "sa",
events: true,
trackPageViews: true,
ignorePages: ["pathname"],
},
},
]
```
--------------------------------
### Configure Gridsome Simple Analytics with Custom Domain
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_gridsome.md
This JavaScript configuration snippet demonstrates how to configure the `gridsome-plugin-simple-analytics` with a custom domain. Specifying a custom domain, like `api.example.com`, can help bypass ad blockers and improve data collection reliability for your analytics.
```js
module.exports = {
plugins: [
{
use: "gridsome-plugin-simple-analytics",
options: {
domain: "api.example.com",
},
},
],
};
```
--------------------------------
### Configure Simple Analytics with custom domain in Nuxt 3
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_nuxt.md
Advanced configuration for the Simple Analytics Nuxt 3 plugin to use a custom domain for bypassing ad-blockers.
```js
import SimpleAnalytics from "simple-analytics-vue";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(SimpleAnalytics, {
skip: process.env.NODE_ENV !== "production",
domain: "api.example.com"
});
});
```
--------------------------------
### Configure Simple Analytics Vue plugin in Nuxt 3
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_nuxt.md
Basic configuration for integrating Simple Analytics into a Nuxt 3 application by creating a client-side plugin.
```js
import SimpleAnalytics from "simple-analytics-vue";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(SimpleAnalytics);
});
```
--------------------------------
### Update Simple Analytics Automated Events Script
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This HTML snippet demonstrates how to update the script tag for Simple Analytics automated events to load `auto-events.js` from your own proxied domain, ensuring consistent traffic routing.
```html
```
--------------------------------
### Track Basic Event in Swift
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Records a custom event in Simple Analytics, useful for tracking user interactions or significant occurrences within the app, such as button clicks or successful operations.
```Swift
SimpleAnalytics.shared.track(event: "logged in")
```
--------------------------------
### cURL command to test event submission
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/50_server-side.md
Example cURL command to send a test event payload to the Simple Analytics events endpoint. This demonstrates how to include custom metadata and a user agent.
```bash
curl -X POST -H "Content-Type: application/json" -d '{
"type": "event",
"hostname": "mobile-app.example.com",
"event": "consent",
"metadata": {
"button": "yes"
},
"ua": "Your User Agent"
}' https://queue.simpleanalyticscdn.com/events
```
--------------------------------
### Update Simple Analytics Embed Script to Use Proxy
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This HTML snippet shows how to update the Simple Analytics embed script to load `proxy.js` from your own domain, ensuring all analytics traffic is routed through your configured proxy.
```html
```
--------------------------------
### Filter API requests using wildcards
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/15_stats-api.md
Demonstrates how to use wildcards (`*`) in API filtering parameters to search for partial matches. Examples include searching for page paths starting with a prefix or containing a specific substring.
```HTTP
https://simpleanalytics.com/simpleanalytics.com.json?version={{ site.api_version }}&fields=pages&pages=/web*
```
```HTTP
https://simpleanalytics.com/simpleanalytics.com.json?version={{ site.api_version }}&fields=pages&pages=*terms*
```
--------------------------------
### Configure Nuxt 2 to include Simple Analytics plugin
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_nuxt.md
Update `nuxt.config.js` to register the Simple Analytics plugin, ensuring it only runs on the client-side by setting `ssr: false`.
```js
// nuxt.config.js
export default {
plugins: [{ src: "~/plugins/simple-analytics.js", ssr: false }],
};
```
--------------------------------
### Install Simple Analytics with JavaScript
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/01_script.md
For environments where direct HTML embedding is not possible, this JavaScript code dynamically creates and appends the Simple Analytics script tag to the document's head. This method achieves the same result as direct HTML inclusion but programmatically.
```js
// Simple Analytics - 100% privacy-first analytics
const script = document.createElement("script");
script.setAttribute("src", "https://scripts.simpleanalyticscdn.com/latest.js");
document.head.appendChild(script);
```
--------------------------------
### Configure Vercel Rewrites for Simple Analytics Proxy
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/25_proxy.md
This JSON configuration for `vercel.json` sets up URL rewrites to proxy Simple Analytics scripts and data collection endpoints through your own domain, enhancing privacy and control. It includes rules for `proxy.js`, `auto-events.js`, and the main `/simple` data endpoint.
```json
{
"rewrites": [
{
"source": "/proxy.js",
"destination": "https://simpleanalyticsexternal.com/proxy.js?hostname=example.com&path=/simple"
},
{
"source": "/auto-events.js",
"destination": "https://scripts.simpleanalyticscdn.com/auto-events.js"
},
{
"source": "/simple/:match*",
"destination": "https://queue.simpleanalyticscdn.com/:match*"
}
]
}
```
--------------------------------
### cURL command to test page view submission
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/55_events/50_server-side.md
Example cURL command to send a test page view payload to the Simple Analytics events endpoint. This command specifies the page type, hostname, and path.
```bash
curl -X POST -H "Content-Type: application/json" -d '{
"type": "pageview",
"hostname": "mobile-app.example.com",
"event": "pageview",
"path": "/my-page-name",
"ua": "Your User Agent"
}' https://queue.simpleanalyticscdn.com/events
```
--------------------------------
### Example Simple Analytics Stats API Request URL
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/15_stats-api.md
Demonstrates how to construct a basic Stats API request URL to retrieve aggregated statistics for a website, including histogram data for yesterday and today.
```HTTP
https://simpleanalytics.com/simpleanalytics.com.json?version={{ site.api_version }}&fields=histogram&start=yesterday&end=today
```
--------------------------------
### Cleaned User-Agent String Example
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/10_general/15_metrics.md
This snippet demonstrates a user-agent string after it has been processed by Simple Analytics. For privacy reasons, long numeric sequences are replaced with zeros, while still retaining essential identification information.
```Text
Mozilla/5.0 (iPad; U; CPU OS 3_2_0) AppleWebKit/531.21.0 (KHTML, like Gecko) Mobile/7B40000
```
--------------------------------
### Embed Simple Analytics Tracking Script for GoDaddy Websites
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_godaddy.md
This JavaScript snippet is intended for insertion into the HTML section of a GoDaddy website. It dynamically loads the Simple Analytics tracking script and allows for custom configuration of the hostname and page path. Users must update the `hostname` variable with their domain (without `https://` or `www.`) and the `path` variable to reflect the specific page being tracked.
```html
```
--------------------------------
### Configure Simple Analytics Rails tracking options in Ruby initializer
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_rubyonrails.md
Customize Simple Analytics behavior in your Ruby on Rails application by creating an initializer file (`config/initializers/simple_analytics.rb`). This allows you to set parameters like `hostname`, `mode`, `collect_dnt`, `ignore_pages`, `sa_global`, `auto_collect`, `onload_callback`, `custom_domain`, and conditionally `enabled` status, providing fine-grained control over tracking.
```Ruby
# config/initializers/simple_analytics.rb
SimpleAnalyticsRails.configure do |configuration|
# ==> Overwrite domain name
# https://docs.simpleanalytics.com/overwrite-domain-name
#
# Default is ""
configuration.hostname = "example.com"
# ==> Hash mode
# https://docs.simpleanalytics.com/hash-mode
#
# Default is ""
configuration.mode = "hash"
# ==> Do not track
# https://docs.simpleanalytics.com/dnt
#
# Default is false
configuration.collect_dnt = false
# ==> Ignore pages
# https://docs.simpleanalytics.com/ignore-pages
#
# Default is ""
configuration.ignore_pages = "/search/*,/account/*,/vouchers"
# ==> Override variable used for JavaScript Events
# https://docs.simpleanalytics.com/events#the-variable-sa_event-is-already-used
#
# Default is "sa_event"
configuration.sa_global = "sa_event"
# ==> Trigger custom page views
# https://docs.simpleanalytics.com/trigger-custom-page-views#use-custom-collection-anyway
#
# Default is true
configuration.auto_collect = true
# ==> Onload Callback
# https://docs.simpleanalytics.com/trigger-custom-page-views#use-custom-collection-anyway
#
# Default is ""
configuration.onload_callback = "onloadCallback()"
# ==> Custom Domain
# https://docs.simpleanalytics.com/bypass-ad-blockers
#
# Default is ""
configuration.custom_domain = "custom.domain.com"
# ==> Inject JavaScript To Head
# You can disable the automatic JavaScript injection if you'd like.
#
# Default is true
configuration.enabled = Rails.env.production?
end
```
--------------------------------
### Simple Analytics Stats API endpoint for event counts
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/20_export-data-points.md
This URL demonstrates how to query the Simple Analytics Stats API to get event counts. It specifies the domain, API version, start and end dates, timezone, and a specific event to filter by (e.g., `visit_pricing`).
```APIDOC
https://simpleanalytics.com/simpleanalytics.com.json?version={{ site.api_version }}&start=yesterday&end=today&timezone=Europe/Amsterdam&events=visit_pricing
```
--------------------------------
### Authenticate Simple Analytics API with API Key and User ID using cURL
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/10_authenticate.md
This cURL example shows how to make an API call that requires both an `Api-Key` and a `User-Id` header. It fetches a list of websites, demonstrating the inclusion of the user ID for specific API features.
```bash
curl "https://simpleanalytics.com/api/websites" \
-H 'Content-Type: application/json' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000'
```
--------------------------------
### Configure Custom Domain for Simple Analytics Plugin
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_docusaurus.md
To use a custom domain for tracking with Simple Analytics, specify the 'domain' property within the plugin's configuration object in 'docusaurus.config.js'. This allows bypassing ad blockers.
```js
plugins: [
...
['docusaurus-plugin-simple-analytics', {
domain: 'custom.domain.com'
}],
...
],
```
--------------------------------
### API Reference: POST /api/websites/add
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/50_api/35_admin.md
Documentation for the endpoint to add a new website. This operation requires a Business or Enterprise plan. Allows specifying website details like hostname, public status, timezone, and an optional label.
```APIDOC
Endpoint: POST https://simpleanalytics.com/api/websites/add
Description: Adds a new website to the user's account.
Authentication: Required (Api-Key, User-Id)
Headers:
Content-Type: application/json
Api-Key: Your Simple Analytics API Key
User-Id: Your Simple Analytics User ID
Request Body (JSON):
public: boolean (optional, default: false)
Description: Sets the website to public or private.
hostname: string (required)
Description: The domain name of the website (e.g., "example.com").
timezone: string (optional, default: UTC)
Description: The timezone for the website (e.g., "Europe/Amsterdam"). See Wikipedia for valid tz database time zones.
label: string (optional)
Description: A custom label for the website, displayed in the dashboard.
```
--------------------------------
### Embed Simple Analytics Light Script
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/00_light.md
Example HTML snippet to embed the light version of the Simple Analytics tracking script on a webpage. It includes an asynchronous script tag for 'light.js' and a 'noscript' fallback for image-based tracking, ensuring basic analytics even when JavaScript is disabled.
```html
```
--------------------------------
### Include HTML Noscript Fallback for Simple Analytics
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/05_analytics.md
This HTML snippet provides a fallback mechanism for browsers with JavaScript disabled. It ensures that Simple Analytics can still track basic page views by loading a GIF pixel, maintaining data collection even in non-JS environments.
```html
```
--------------------------------
### Add Simple Analytics Swift Package Dependency
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/31_integrations/00_swift.md
Instructions for adding the Simple Analytics Swift package to an iOS project. This can be done either through Xcode's 'Add package dependency' feature by providing the repository URL or by manually adding the dependency to a Swift package manifest file.
```Text
https://github.com/simpleanalytics/swift-package.git
```
```Swift
.package(url: "https://github.com/simpleanalytics/swift-package.git", from: "0.3.0")
```
--------------------------------
### Jekyll Documentation Item Display with Special Links
Source: https://github.com/simpleanalytics/docs/blob/master/_layouts/default.html
This Jekyll Liquid snippet iterates through documentation items within a category, displaying their menu title or regular title. It also adds 'new' tag based on creation date and includes specific platform/framework guides or event links for 'integrations' and 'features' categories.
```liquid
{% assign items = cat.items | sort: 'path' %}
{% for item in items %}
{% if item.hidden != true %}* [{% if item.menu %} {{ item.menu }} {% else %} {{ item.title }} {% endif %} {% capture date %}{{ item.created_at | date: '%s' | plus: 0 }}{% endcapture %} {% if date > new %} new {% endif %}]({{ item.url }})
{% endif %} {% endfor %} {% if cat.name == 'integrations' %}* [Platform guides](/install-on-other-platforms#platform-guides)
* [Framework plugins](/install-on-other-platforms#framework-plugins)
{% endif %} {% if cat.name == 'features' %}* [Events](/events)
{% endif %}
```
--------------------------------
### HTML setup for manual page view collection with `sa_pageview`
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/20_install-script/02_custom.md
This HTML snippet shows how to integrate Simple Analytics with manual page view control. By setting `data-auto-collect="false"`, automatic tracking is disabled. The `saLoaded` function, called on script load, then uses `window.sa_pageview` to send a page view, demonstrating how to trigger events programmatically.
```html
```
--------------------------------
### Initialize Simple Analytics Event Helper
Source: https://github.com/simpleanalytics/docs/blob/master/_docs/33_explained/20_platform-integration.md
This optional JavaScript helper can be included in the `` of every customer page. It buffers event calls and automatically sends them to Simple Analytics if the main script is enabled, otherwise, events are ignored.
```JavaScript
window.sa_event = window.sa_event || function () {
const a = [].slice.call(arguments);
window.sa_event.q ? window.sa_event.q.push(a) : window.sa_event.q = [a];
};
```