### Run Framer Plugin Development Server (Bash)

Source: https://github.com/simpleanalytics/framer-plugin/blob/main/README.md

Commands to start the development server for the Framer plugin. These commands are typically run in a terminal and utilize package managers like npm, yarn, pnpm, or bun.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun dev
```

--------------------------------

### Install, Remove, and Update Analytics Script (TypeScript)

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Provides functions to manage the Simple Analytics script within a Framer project. This includes installing/updating the script, removing it entirely, and updating individual settings followed by a script regeneration.

```typescript
import { framer } from "framer-plugin";
import { createScript } from "./lib/script";

// Install/update analytics script
async function installScript() {
  const scriptHtml = await createScript();
  await framer.setCustomCode({
    html: scriptHtml,
    location: "bodyEnd",
  });
}

// Remove analytics script
async function removeScript() {
  await framer.setCustomCode({
    html: null,
    location: "bodyEnd",
  });
}

// Update single setting and regenerate script
async function updateSetting(key: string, value: string | null) {
  await framer.setPluginData(key, value);
  await installScript(); // Regenerate with new settings
}

// Usage
await updateSetting("data-hostname", "example.com");
await updateSetting("data-ignore-pages", "/admin/*");
```

--------------------------------

### Subscribe to Custom Code Changes (React/TypeScript)

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

A React hook that subscribes to changes in custom code within a Framer project, providing real-time updates. It's useful for checking the installation status or current content of analytics scripts.

```typescript
import { useCustomCode } from "./hooks/use-custom-code";

function AnalyticsPanel() {
  const customCode = useCustomCode();

  // Check loading state
  const isLoading = !customCode;

  // Check if analytics script is installed
  const isInstalled = customCode?.bodyEnd.html != null;

  // Access current script content
  if (customCode?.bodyEnd.html) {
    console.log("Current script:", customCode.bodyEnd.html);
  }

  return (
    <div>
      {isLoading ? "Loading..." : isInstalled ? "Installed" : "Not installed"}
    </div>
  );
}
```

--------------------------------

### Complete Framer Plugin Workflow for Analytics

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Demonstrates a full implementation workflow for the Simple Analytics Framer Plugin, including initialization, settings management, and script updates. It uses React hooks for state management and Framer's API for custom code and plugin data. This snippet shows how to load settings, install/remove the script, toggle events, and set custom domains.

```typescript
import { framer } from "framer-plugin";
import { useState, useEffect } from "react";
import { parseSettings, type Settings } from "./lib/settings";
import { createScript } from "./lib/script";
import { useCustomCode } from "./hooks/use-custom-code";

function AnalyticsPlugin() {
  const customCode = useCustomCode();
  const [settings, setSettings] = useState<Settings | null>(null);

  const isLoading = !customCode;
  const isInstalled = customCode?.bodyEnd.html != null;

  // Load settings on mount
  useEffect(() => {
    parseSettings().then(setSettings);

    // Auto-install if not installed
    if (!isInstalled && !isLoading) {
      updateScript();
    }
  }, [isInstalled, isLoading]);

  // Regenerate and inject script
  const updateScript = async () => {
    const html = await createScript();
    await framer.setCustomCode({
      html,
      location: "bodyEnd",
    });
  };

  // Update individual setting
  const updateSetting = async (key: string, value: string | null) => {
    await framer.setPluginData(key, value);
    setSettings((prev) => prev ? { ...prev, [key]: value } : prev);
    await updateScript();
  };

  // Remove script entirely
  const removeScript = async () => {
    await framer.setCustomCode({
      html: null,
      location: "bodyEnd",
    });
  };

  // Toggle automated events
  const toggleAutoEvents = async (enabled: boolean) => {
    await updateSetting(
      "setting-auto-collect-events",
      enabled ? null : "false"
    );
  };

  // Set custom domain
  const setCustomDomain = async (domain: string) => {
    await updateSetting(
      "setting-custom-domain",
      domain.trim() === "" ? null : domain
    );
  };

  return (
    <div>
      <h1>Simple Analytics Configuration</h1>
      <p>Status: {isInstalled ? "Installed" : "Not Installed"}</p>

      <button onClick={() => toggleAutoEvents(true)}>
        Enable Auto Events
      </button>

      <button onClick={() => setCustomDomain("cdn.example.com")}>
        Set Custom Domain
      </button>

      <button onClick={isInstalled ? removeScript : updateScript}>
        {isInstalled ? "Remove" : "Install"} Script
      </button>
    </div>
  );
}
```

--------------------------------

### Settings Retrieval

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Retrieves all current plugin configuration settings stored persistently within Framer.

```APIDOC
## GET /simpleanalytics/framer-plugin/settings

### Description
Fetches all configuration settings for the Simple Analytics plugin that are stored in Framer's persistent data storage. This provides a complete overview of the current analytics setup.

### Method
GET

### Endpoint
/simpleanalytics/framer-plugin/settings

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **settings** (object) - An object containing all current plugin settings.
  - **setting-auto-collect-events** (string) - "true" or "false".
  - **setting-custom-domain** (string) - Custom CDN domain.
  - **data-auto-collect** (string) - "true" or "false".
  - **data-hostname** (string) - Hostname for analytics.
  - **data-collect** (string) - Comma-separated list of events to collect.
  - **data-extensions** (string) - Comma-separated list of file extensions.
  - **data-ignore-pages** (string) - Comma-separated list of pages to ignore.
  - **data-collect-dnt** (string) - "true" or undefined.
  - **data-mode** (string) - "hash" or undefined.
  - **auto-event-partial-collect-downloads** (string) - "true" or undefined.
  - **auto-event-partial-collect-outbound** (string) - "true" or undefined.
  - **auto-event-partial-collect-emails** (string) - "true" or undefined.

#### Response Example
```json
{
  "settings": {
    "setting-auto-collect-events": "true",
    "data-auto-collect": "true",
    "data-hostname": "example.com",
    "data-collect": "downloads,outbound,emails",
    "data-extensions": "pdf,csv",
    "data-ignore-pages": "/admin/*,/dashboard/*"
  }
}
```
```

--------------------------------

### Manage Framer Plugin Data (TypeScript)

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Demonstrates how to store and retrieve plugin configuration data using the Framer Plugin API. Settings can be saved, retrieved, and removed by passing `null` as the value.

```typescript
import { framer } from "framer-plugin";

// Save a setting (null removes the setting)
await framer.setPluginData("setting-custom-domain", "cdn.example.com");
await framer.setPluginData("data-auto-collect", "false");
await framer.setPluginData("data-ignore-pages", "/admin/*,/dashboard/*");

// Retrieve a setting
const customDomain = await framer.getPluginData("setting-custom-domain");
const autoCollect = await framer.getPluginData("data-auto-collect");

// Remove a setting (pass null)
await framer.setPluginData("setting-custom-domain", null);

// Common settings keys:
// - "setting-auto-collect-events": "true" | "false" | undefined
// - "data-collect-dnt": "true" | undefined (collect Do Not Track users)
// - "data-mode": "hash" | undefined (enable hash routing)
// - "data-ignore-pages": string (comma-separated paths with wildcards)
```

--------------------------------

### Retrieve Plugin Settings (TypeScript)

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Retrieves all plugin configuration settings stored in Framer's persistent storage. It utilizes a local `lib/settings` module to parse these settings into a structured object.

```typescript
import { parseSettings, type Settings } from "./lib/settings";

// Load all plugin settings
const settings: Settings = await parseSettings();

// Access specific settings
console.log(settings["setting-custom-domain"]); // Custom CDN domain
console.log(settings["data-auto-collect"]); // Page view collection setting
console.log(settings["auto-event-partial-collect-downloads"]); // Download tracking

// Settings structure includes:
// - setting-auto-collect-events: Enable/disable automated event tracking
// - setting-custom-domain: Custom domain for script loading
// - auto-event-partial-collect-*: Granular event collection toggles
// - data-*: Analytics behavior attributes (DNT, hostname, mode, etc.)
```

--------------------------------

### Configure Event Tracking with Framer Plugin

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Enables and configures automated event tracking for user interactions like downloads, outbound links, and email clicks. It allows customization of file extensions for downloads and collection of page titles and full URLs. Uses `framer.setPluginData` to manage these settings.

```typescript
import { framer } from "framer-plugin";

// Enable specific event types
async function configureEventTracking() {
  // Track downloads (PDF, CSV, DOCX, etc.)
  await framer.setPluginData(
    "auto-event-partial-collect-downloads",
    null // null = enabled (default)
  );

  // Track outbound links
  await framer.setPluginData(
    "auto-event-partial-collect-outbound-links",
    null // enabled
  );

  // Track email clicks
  await framer.setPluginData(
    "auto-event-partial-collect-email-clicks",
    "false" // disabled
  );

  // Customize download file extensions
  await framer.setPluginData(
    "auto-event-data-extensions",
    "pdf,zip,mp4,avi"
  );

  // Enable page title collection in events
  await framer.setPluginData(
    "auto-event-data-use-title",
    null // enabled (default)
  );

  // Collect full URLs instead of paths only
  await framer.setPluginData(
    "auto-event-data-full-urls",
    "true" // enabled
  );
}
```

--------------------------------

### Script Generation and Injection

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Generates Simple Analytics script tags based on configured settings and injects them into the Framer site's HTML.

```APIDOC
## POST /simpleanalytics/framer-plugin/script

### Description
Generates and injects Simple Analytics tracking scripts into the Framer site. This function reads user settings and constructs the necessary script tags, applying them to the end of the HTML body.

### Method
POST

### Endpoint
/simpleanalytics/framer-plugin/script

### Parameters
#### Request Body
- **settings** (object) - Optional - Configuration settings for the analytics script. If not provided, the function will attempt to retrieve current settings.
  - **autoCollect** (boolean) - Optional - Whether to automatically collect page views.
  - **hostname** (string) - Optional - The custom hostname for script loading.
  - **collectEvents** (array<string>) - Optional - List of events to automatically collect (e.g., `["downloads", "outbound", "emails"]`).
  - **extensions** (array<string>) - Optional - File extensions to consider as downloads.
  - **ignorePages** (string) - Optional - Comma-separated list of page paths to ignore.
  - **collectDNT** (boolean) - Optional - Whether to collect data from users with Do Not Track enabled.
  - **mode** (string) - Optional - Analytics mode (e.g., `"hash"`).

### Request Example
```json
{
  "settings": {
    "autoCollect": true,
    "hostname": "example.com",
    "collectEvents": ["downloads", "outbound"],
    "ignorePages": "/admin/*,/dashboard/*"
  }
}
```

### Response
#### Success Response (200)
- **scriptHtml** (string) - The generated HTML script tags for Simple Analytics.

#### Response Example
```json
{
  "scriptHtml": "<script async src=\"https://scripts.simpleanalyticscdn.com/latest.js\" data-auto-collect=\"true\" data-hostname=\"example.com\"></script><script async src=\"https://scripts.simpleanalyticscdn.com/auto-events.js\" data-collect=\"downloads,outbound\" data-extensions=\"pdf,csv\"></script>"
}
```
```

--------------------------------

### Configure Advanced Analytics with Framer Plugin

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Sets up advanced analytics configurations including Do Not Track, disabling automatic page view collection, overriding hostnames, enabling hash mode for SPAs, and ignoring specific pages. It also allows setting a custom CDN domain and disabling all automated events. Uses `framer.setPluginData` for configuration.

```typescript
import { framer } from "framer-plugin";

// Configure advanced settings
async function configureAdvancedSettings() {
  // Enable Do Not Track collection
  await framer.setPluginData("data-collect-dnt", "true");

  // Disable automatic page view collection
  await framer.setPluginData("data-auto-collect", "false");

  // Override hostname for multi-domain tracking
  await framer.setPluginData("data-hostname", "example.com");

  // Enable hash mode for SPA routing
  await framer.setPluginData("data-mode", "hash");

  // Ignore specific pages (supports wildcards)
  await framer.setPluginData(
    "data-ignore-pages",
    "/admin/*,/dashboard/*,/test"
  );

  // Use custom CDN domain (bypass ad blockers)
  await framer.setPluginData(
    "setting-custom-domain",
    "analytics.mysite.com"
  );

  // Disable all automated events
  await framer.setPluginData("setting-auto-collect-events", "false");
}
```

--------------------------------

### Custom Code Management

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

APIs for managing custom HTML code injected into the Framer project, specifically for script injection and removal.

```APIDOC
## Custom Code Injection/Removal

### Description
Allows for the programmatic management of custom HTML code within a Framer project. This is primarily used to install or remove the Simple Analytics tracking script by injecting or clearing HTML in specific locations like the end of the body.

### Method
POST

### Endpoint
/framer-plugin/custom-code

### Parameters
#### Request Body
- **html** (string | null) - Required - The HTML content to inject. Set to `null` to remove existing custom code at the specified location.
- **location** (string) - Required - The location within the HTML document where the code should be injected (e.g., `"head"`, `"bodyEnd"`).

### Request Example (Install Script)
```json
{
  "html": "<script async src=\"https://scripts.simpleanalyticscdn.com/latest.js\"></script>",
  "location": "bodyEnd"
}
```

### Request Example (Remove Script)
```json
{
  "html": null,
  "location": "bodyEnd"
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message (e.g., "Custom code updated successfully.").

#### Response Example
```json
{
  "status": "Custom code updated successfully."
}
```
```

--------------------------------

### Generate and Inject Simple Analytics Scripts (TypeScript)

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

Generates Simple Analytics script tags based on user settings and injects them into the Framer site's HTML at the end of the body. This function requires the `framer-plugin` and a local `lib/script` module.

```typescript
import { framer } from "framer-plugin";
import { createScript } from "./lib/script";

// Generate analytics scripts with user settings
const scriptHtml = await createScript();

// Example output:
// <script async src="https://scripts.simpleanalyticscdn.com/latest.js" data-auto-collect="false" data-hostname="example.com"></script>
// <script async src="https://scripts.simpleanalyticscdn.com/auto-events.js" data-collect="downloads,outbound,emails" data-extensions="pdf,csv"></script>

// Inject into Framer site
await framer.setCustomCode({
  html: scriptHtml,
  location: "bodyEnd",
});
```

--------------------------------

### Framer Plugin Data Management

Source: https://context7.com/simpleanalytics/framer-plugin/llms.txt

APIs for storing and retrieving arbitrary plugin data using Framer's built-in data persistence.

```APIDOC
## Managment of Plugin Data

### Description
Provides functions to interact with Framer's plugin data storage. You can set key-value pairs, retrieve values by key, and remove data by setting a key to null. This is used to store and manage the analytics configuration.

### Method
POST (for setting/removing), GET (for retrieving)

### Endpoint
- **Set/Remove Data**: `/framer-plugin/data/{key}`
- **Get Data**: `/framer-plugin/data/{key}`

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the data entry.

#### Request Body (for Set/Remove)
- **value** (string | null) - Required - The data to store, or null to remove the entry.

### Request Example (Set Data)
```json
{
  "value": "cdn.example.com"
}
```

### Response
#### Success Response (200)
- **For Set/Remove**: No explicit response body, operation is confirmed by absence of error.
- **For Get**: 
  - **value** (string | null) - The retrieved data associated with the key, or null if not found.

#### Response Example (Get Data)
```json
{
  "value": "cdn.example.com"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.