# Nonaki: full documentation

> A WordPress link management plugin for creating clean redirects and tracking audience performance.

============================================================
Nonaki
============================================================

---

URL: https://docs.affkraft.com/nonaki
Markdown: https://docs.affkraft.com/nonaki.md

# Nonaki Plugin

Nonaki is a WordPress link management plugin built for site owners, marketers, and affiliates. Create clean redirect links, track clicks and impressions, detect broken destinations, and understand your audience — all from your WordPress dashboard.

***

## Getting Started

Follow the documentation to install the plugin and start managing your links.

### Requirements

Before getting started make sure your server meets the minimum requirements.

* `WordPress 6.0` or higher (recommended: latest stable)
* `PHP 8.4` or higher
* PHP `max_upload_size` above `4MB` (for import)

### Changelog

Find the full changelog [here](https://affkraft.com/changelog?product=nonaki).

---

URL: https://docs.affkraft.com/nonaki/installation
Markdown: https://docs.affkraft.com/nonaki/installation.md

# Plugin Installation

You can install the plugin either through the WordPress dashboard (recommended) or via FTP.

***

## Before Installation

Make sure your server meets the minimum [system requirements](https://docs.affkraft.com/nonaki) and download the plugin file from your [AffKraft account](https://affkraft.com/login).

### Install through WordPress Dashboard

1. Visit WordPress dashboard → **Plugins** and click `Add New`, then `Upload Plugin`
2. Click `Choose File`, select `nonaki.zip` and click `Install Now`
3. Activate the plugin

### Install via FTP

1. Log in to your server using an FTP client, cPanel, or similar
2. Navigate to the `plugins` directory in your WordPress root
3. Upload `nonaki.zip` and unzip it — you should have a `nonaki` directory in `plugins`
4. Remove the `nonaki.zip` file
5. Visit WordPress dashboard → **Plugins** and activate the plugin

---

URL: https://docs.affkraft.com/nonaki/upgrading-from-v1
Markdown: https://docs.affkraft.com/nonaki/upgrading-from-v1.md

# Upgrading from v1 to v2

v2 is a full rewrite with a new interface and expanded analytics. The upgrade takes about a minute.

***

## What's preserved

* All your links (keys and destinations)
* The redirect slug

***

## Upgrade steps

1. Download the v2 plugin zip from your [AffKraft account](https://affkraft.com/login)
2. Go to **WordPress dashboard → Plugins → Add New → Upload Plugin**
3. Upload the zip and click **Install Now**, then **Replace current with uploaded**
4. Back to **plugins page**
5. **Deactivate** the plugin, then **Activate** it again

The deactivate/activate step is required — it triggers the database migration that creates the new analytics tables.

***

## "You are not allowed to access this page"

If you click on "Nonaki Links" link in the sidebar and see this error after uploading but before reactivating, don't panic — the admin page URL changed in v2. Deactivate and reactivate the plugin and the error will go away.

***

## After upgrading

Navigate to **Nonaki** in the sidebar. Your links will be there. The analytics section will be empty until your links start receiving traffic.

---

URL: https://docs.affkraft.com/nonaki/links
Markdown: https://docs.affkraft.com/nonaki/links.md

# Managing Links

Nonaki turns long or ugly URLs into clean redirect links on your own domain. All links are managed from the **Nonaki** menu in your WordPress dashboard.

***

## Redirect Slug

The redirect slug is the base path that appears in all your links. The default is `links`, producing URLs like `yoursite.com/links/your-key`. You can change it in [**Settings**](https://docs.affkraft.com/nonaki/settings) at any time.

***

## Creating a Link

Click `Add New` to open the create form. You need two things:

* **Link Key** — the short identifier that appears in the URL (e.g. `affkraft`). Letters, numbers, hyphens, and underscores are allowed.
* **Destination URL** — the full URL visitors are sent to.

You can also set the **Redirect Type**:

* `301` — Moved Permanently (default; best for SEO and affiliate links)
* `302` — Found (temporary redirect)
* `307` — Temporary Redirect (preserves the HTTP method)

Once saved, the full redirect URL is shown in the links list and can be copied with one click.

***

## Managing Links

All links are listed in the **Links** view with the following options:

* **Search** — filter by link key or destination URL
* **Tag filter** — show only links with a specific tag
* **Edit** — update the destination URL, link key, or redirect type
* **Copy** — copy the full redirect URL to the clipboard
* **Trash** — move the link to trash (stops the redirect immediately)

### Broken Link Badge

If the link checker detects that a destination URL is unreachable, the link row displays a `broken` badge. See [Link Checker](https://docs.affkraft.com/nonaki/link-checker) for details.

***

## Tags

Tags help you organize links into groups. You can create and manage tags from the **Tags** section, then assign one or more tags to any link.

The links list can be filtered by tag to quickly find a subset of your links.

***

## Trash

Trashed links no longer redirect visitors but are kept in the database. Visit the **Trash** tab to:

* **Restore** — return a link to active status
* **Force Delete** — permanently remove the link and all associated analytics data

***

## Bulk Actions

Select multiple links using the checkboxes to apply bulk actions:

* **Trash selected**
* **Restore selected** (Trash view)
* **Permanently delete selected** (Trash view)

---

URL: https://docs.affkraft.com/nonaki/analytics
Markdown: https://docs.affkraft.com/nonaki/analytics.md

# Analytics

Nonaki tracks both clicks (when a visitor follows a redirect) and impressions (when a page containing your link is viewed). Open any link's analytics from the **Links** view to see its performance.

***

## Clicks

A click is recorded every time a visitor follows one of your redirect links. Nonaki captures:

* Date and time
* Device type, browser, and operating system
* Country (from CDN headers if available, otherwise from [GeoIP](https://docs.affkraft.com/nonaki/geoip) if configured)
* Referrer URL
* Whether the visitor was identified as a bot

Clicks are processed asynchronously — recorded to a queue first, then enriched and moved to the analytics tables by a background job that runs every 5 minutes. This helps keep the redirects fast while being able to track click activities.

***

## Impressions

An impression is recorded when a page on your site that contains one of your links is loaded. The tracking is handled by a lightweight beacon that fires in the background and does not affect page load time.

Impressions capture:

* Date and time
* Device type, browser, and operating system
* Country (from CDN headers if available, otherwise from [GeoIP](https://docs.affkraft.com/nonaki/geoip) if configured)
* The page URL where the link appeared

To avoid inflating counts, a maximum of one impression per visitor per link per page is recorded within any 60-second window.

***

## Bot Detection

Both clicks and impressions are checked for bot traffic. Nonaki uses device/user-agent analysis combined with a list of known datacenter and ASN IP ranges. Bot events are stored but excluded from the default analytics view so your numbers reflect real visitors.

***

## Analytics View

Click the chart icon on any link row to open its analytics. The view includes:

### Chart

A dual-axis chart showing daily clicks and impressions over the selected time range. Bots are excluded by default.

### Stat Cards

Four summary cards at a glance:

* **Total Clicks**
* **Total Impressions**
* **CTR** — click-through rate (clicks ÷ impressions)
* **Avg Clicks / Day**

### Breakdowns

Detailed tables showing the distribution of traffic by:

* **Device** — Desktop, Mobile, Tablet
* **Browser** — Chrome, Firefox, Safari, etc.
* **Operating System** - MacOS, Linux, Windows, iOS, Android, etc.
* **Country** — requires GeoIP to be configured
* **Referrer** — top referring domains
* **Top Pages** — pages on your site where the link appeared (impressions only)

### Time Range

Use the selector in the top-right to change the time window: `7 days`, `30 days`, `90 days`, `1 year`, or `All time`.

---

URL: https://docs.affkraft.com/nonaki/geoip
Markdown: https://docs.affkraft.com/nonaki/geoip.md

# GeoIP

Nonaki can detect the country of your visitors using IP geolocation. When enabled, country data appears in click and impression analytics breakdowns.

GeoIP is optional. All other features work without it.

Nonaki uses 2 ways to detect the visitor's country: CDN headers or MaxMind GeoLite2.

***

## CDN and Proxy Support

If your site is behind Cloudflare or a similar CDN, Nonaki will attempt to read the country from CDN-provided headers (such as `CF-IPCountry`) before falling back to local GeoIP lookup. This means country detection can work even if you are not using the MaxMind database.

***

## MaxMind GeoLite2

Nonaki uses the free **MaxMind GeoLite2** database for geolocation. You need a free MaxMind account to download it.

### 1. Create a MaxMind Account

Sign up for a free account at [maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup). No payment is required for GeoLite2.

### 2. Generate a License Key

After logging in, go to **Account** → **Manage License Keys** and generate a new key.

### 3. Add the Key in Nonaki

Go to **Nonaki** → **Settings** → **GeoIP Database**. Paste your license key and click `Save & Update`.

Nonaki will download the GeoLite2 database files immediately. You should see the database status update to show both `GeoLite2-City` and `GeoLite2-ASN` as present.

***

## Auto-Update

MaxMind updates the GeoLite2 databases regularly. Enable **Auto-update databases weekly** in the GeoIP settings to keep your data current automatically. When enabled, Nonaki checks for updates once a week via a background cron job.

You can also trigger an update manually at any time by saving the GeoIP settings.

***

## Privacy

IP addresses are used only to determine the visitor's country and are not stored in their original form in analytics. See [Privacy & GDPR](https://docs.affkraft.com/nonaki/privacy) for details.

---

URL: https://docs.affkraft.com/nonaki/link-checker
Markdown: https://docs.affkraft.com/nonaki/link-checker.md

# Link Checker

Nonaki automatically checks whether your redirect destinations are still reachable and flags any that return an error or are unreachable.

***

## How It Works

Once a day, Nonaki sends a HEAD request to each active redirect destination and records the HTTP response code. Links that return a `4xx` or `5xx` response, or that time out, are marked as broken.

Checks run in the background via WordPress cron and process links in small batches to avoid timeouts on sites with a large number of links.

***

## Broken Link Badge

When a link's destination is unreachable, a `broken` badge appears on its row in the Links view. The badge is removed automatically the next time the checker runs and the link responds successfully.

***

## Email Digest

Nonaki sends an email notification when links become broken — meaning only links that were working on the previous check and are now failing. Links that were already flagged as broken are not included again.

The email goes to the WordPress admin email address and lists each newly broken link with its destination URL and the HTTP response code received.

***

## On-Demand Check

You can run a link check at any time without waiting for the daily cron. Go to **Links** and click `Check Links` button on the top toolbar. Results are shown inline — and each broken link displays a "broken" red badge.

---

URL: https://docs.affkraft.com/nonaki/import-export
Markdown: https://docs.affkraft.com/nonaki/import-export.md

# Import & Export

Nonaki supports importing and exporting your links in CSV and JSON formats, making it easy to migrate links, create backups, or manage large sets of links outside WordPress.

***

## Exporting Links

Go to **Nonaki** → **Settings** → **Import & Export** and click `Export CSV` or `Export JSON` to download all your active links, including their tags.

***

## Importing Links

To import links, prepare a file in the correct format (see below) and upload it using the import form in **Nonaki** → **Settings** → **Import & Export**.

**Import behaviour:**

* Links with a key that already exists in Nonaki are skipped — existing links are never overwritten
* Each row is validated individually; invalid rows are skipped
* Tags are created automatically if they do not already exist

After the import completes, a summary shows how many links were imported and how many were skipped.

### Downloading a Template

Click `template.json` or `template.csv` to get an example JSON/CSV file with the correct format/column headers ready to fill in.

***

## CSV Format

| Column          | Required | Description                                              |
| --------------- | -------- | -------------------------------------------------------- |
| link_key        | Yes      | The short key used in the redirect URL                   |
| destination_url | Yes      | The full destination URL                                 |
| redirect_type   | No       | `301`, `302`, or `307` (defaults to `302`)               |
| tags            | No       | One or more tag names separated by pipe character - "|" |

**Example:**

```csv
link_key,destination_url,redirect_type,tags
affkraft,https://affkraft.com/web-development,301,wordpress|web-development
tablrr,https://tablrr.app/the-tablrr-way,302,listings
```

***

## JSON Format

JSON export produces an array of link objects. The same fields apply.

**Example:**

```json
[
  {
    "link_key": "affkraft",
    "destination_url": "https://affkraft.com/web-development",
    "redirect_type": 301,
    "tags": ["wordpress", "web-development"]
  },
  {
    "link_key": "tablrr",
    "destination_url": "https://tablrr.app/the-tablrr-way",
    "redirect_type": 302,
    "tags": ["listings"]
  }
]
```

---

URL: https://docs.affkraft.com/nonaki/settings
Markdown: https://docs.affkraft.com/nonaki/settings.md

# Settings

All plugin settings are in **Nonaki** → **Settings** in your WordPress dashboard.

***

## Redirect Slug

The redirect slug is the base path for all your links. The default is `links`, producing URLs like `yoursite.com/links/your-key`.

You can change it to anything you like — `go`, `visit`, `out`, or something custom. After saving, all existing redirects automatically use the new slug.

If you have set the slug via a code filter (`nonaki_slug`), the field will be locked and a notice will indicate that it is managed by code.

***

## GeoIP

Configure visitor country detection using the MaxMind GeoLite2 database.

* **MaxMind License Key** — paste your key here and click `Save & Update` to download the database files immediately. The field is write-only; for security the key is not displayed after saving.
* **Auto-update databases weekly** — enable to keep the GeoLite2 database current via a weekly background update.
* **Database status** — shows whether the `GeoLite2-City` and `GeoLite2-ASN` files are present and the date they were last updated.

See [GeoIP](https://docs.affkraft.com/nonaki/geoip) for full setup instructions.

***

## Import & Export

Upload a CSV or JSON file to import links in bulk, or download all your links for backup or migration. See [Import & Export](https://docs.affkraft.com/nonaki/import-export) for file format details and a downloadable template.

***

## Clear Analytics Data

The `Clear All Analytics` button permanently deletes all recorded clicks and impressions. Use this to start fresh or to fulfill a GDPR erasure request. This action cannot be undone.

---

URL: https://docs.affkraft.com/nonaki/integrations
Markdown: https://docs.affkraft.com/nonaki/integrations.md

# Integrations

Nonaki exposes a REST API that allows third-party tools and services to manage your redirects and read your click and impression data. Access is controlled by two separate API keys you manage from the **Integrations** tab in the plugin.

***

## API Keys

Go to **Nonaki** → **Integrations** to view and manage your API keys.

For each key:

* **Copy** — copy the key to your clipboard to paste into a third-party service
* **Regenerate** — generate a new key immediately. The old key stops working as soon as you regenerate. Make sure to update any service using the old key.

### Links API Key

Grants access to the redirects and tags endpoints. Use this to let external tools create, update, or delete your links.

Keep this key private. Anyone who has it can read and modify all your redirects and tags.

### Stats API Key

Grants access to the stats endpoints. Use this to let external tools read your click and impression data.

Keep this key private. Anyone who has it can read all your click and impression data.

***

## Authentication

All API requests must include the key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

Requests without a valid key receive a `401 Unauthorized` response.

***

## Links Endpoints

All endpoints are under `https://yoursite.com/wp-json/nonaki/v2/` and require the **Links API Key**.

### The redirect object

```json
{
  "id": 42,
  "link_key": "affkraft",
  "destination_url": "https://affkraft.com/themes",
  "redirect_type": 301,
  "status": "active",
  "link_status": "ok",
  "click_count": 1024,
  "impression_count": 8820,
  "tags": [{ "id": 3, "name": "Themes", "slug": "themes" }],
  "created_at": "2025-11-04 09:15:00",
  "updated_at": "2026-03-19 14:22:11"
}
```

`redirect_type` is `301`, `302`, or `307`. `status` is `active` or `trashed`. `link_status` is `ok`, `broken`, or `unchecked`.

***

### GET /redirects

Returns a paginated list of redirects.

**Query parameters:**

| Parameter  | Default  | Description                              |
| ---------- | -------- | ---------------------------------------- |
| `page`     | `1`      | Page number.                             |
| `per_page` | `20`     | Results per page (max `100`).            |
| `search`   | —        | Filter by key or destination URL.        |
| `status`   | `active` | Filter by status: `active` or `trashed`. |
| `tag_id`   | —        | Filter by tag ID.                        |

**Response:**

```json
{
  "data": [{ "id": 42, "link_key": "affkraft", "...": "..." }],
  "total": 120,
  "pages": 6
}
```

***

### POST /redirects

Creates a new redirect.

**Body:**

| Field             | Required | Description                                        |
| ----------------- | -------- | -------------------------------------------------- |
| `link_key`        | Yes      | Short key used in the redirect URL (e.g. `promo`). |
| `destination_url` | Yes      | The URL to redirect to.                            |
| `redirect_type`   | Yes      | `301`, `302`, or `307`.                            |
| `tag_ids`         | No       | Array of tag IDs to assign.                        |

Returns the created redirect object with status `201 Created`.

***

### GET /redirects/{id}

Returns a single redirect by ID.

***

### PATCH /redirects/{id}

Updates a redirect. All fields are optional — only send what you want to change.

**Body:** any combination of `link_key`, `destination_url`, `redirect_type`, `tag_ids`.

Sending `tag_ids` replaces the redirect's tags entirely.

***

### DELETE /redirects/{id}

Moves the redirect to trash. Returns `204 No Content`. Use `POST /redirects/{id}/restore` to undo.

***

### POST /redirects/{id}/restore

Restores a trashed redirect back to active. Returns the redirect object.

***

### DELETE /redirects/{id}/force-delete

Permanently deletes a redirect. This cannot be undone. Returns `204 No Content`.

***

### POST /redirects/bulk

Applies an action to multiple redirects at once.

**Body:**

| Field     | Required                          | Description                                                          |
| --------- | --------------------------------- | -------------------------------------------------------------------- |
| `action`  | Yes                               | One of: `trash`, `restore`, `force-delete`, `tag-add`, `tag-remove`. |
| `ids`     | Yes                               | Array of redirect IDs.                                               |
| `tag_ids` | For `tag-add` / `tag-remove` only | Array of tag IDs to add or remove.                                   |

**Response:**

```json
{ "affected": 5 }
```

***

### GET /tags

Returns all tags.

**Response:**

```json
{
  "data": [{ "id": 3, "name": "Themes", "slug": "themes", "link_count": 12 }]
}
```

***

### POST /tags

Creates a new tag.

**Body:** `name` (required).

Returns the created tag object with status `201 Created`:

```json
{ "data": { "id": 4, "name": "Plugins", "slug": "plugins" } }
```

***

### PATCH /tags/{id}

Updates a tag's name. **Body:** `name` (required). Returns the updated tag object.

***

### DELETE /tags/{id}

Permanently deletes a tag. Returns `204 No Content`.

***

## Stats Endpoints

All endpoints are under `https://yoursite.com/wp-json/nonaki/v2/` and require the **Stats API Key**.

### GET /stats/links

Returns a paginated list of all active links.

**Query parameters:** same as `/stats/clicks` (`after_id`, `per_page`).

**Response:**

```json
{
  "data": [
    {
      "id": 12,
      "link_key": "affkraft",
      "destination_url": "https://affkraft.com/themes",
      "redirect_type": "301",
      "created_at": "2025-11-04 09:15:00"
    }
  ],
  "meta": {
    "per_page": 100,
    "has_more": false,
    "last_id": 12
  }
}
```

***

### GET /stats/clicks

Returns a paginated list of raw click events.

**Query parameters:**

| Parameter  | Default | Max   | Description                                                                |
| ---------- | ------- | ----- | -------------------------------------------------------------------------- |
| `after_id` | `0`     | —     | Return only clicks with an ID greater than this value. Use for pagination. |
| `per_page` | `100`   | `500` | Number of results per page.                                                |

**Response:**

```json
{
  "data": [
    {
      "id": 1042,
      "link_key": "affkraft",
      "destination_url": "https://affkraft.com/themes",
      "occurred_at": "2026-03-19 14:22:11",
      "device_type": "desktop",
      "browser": "Chrome",
      "os": "Windows",
      "country_code": "US",
      "referer": "https://yoursite.com/best-gambling-wp-themes/",
      "ip_hash": "a3f1c9...",
      "bot_detected": false,
      "bot_name": null
    }
  ],
  "meta": {
    "per_page": 100,
    "has_more": true,
    "last_id": 1042
  }
}
```

***

### GET /stats/impressions

Returns a paginated list of raw impression events.

**Query parameters:** same as `/stats/clicks`.

**Response:** same structure as clicks, with `page_url` instead of `referer`:

```json
{
  "data": [
    {
      "id": 8801,
      "link_key": "affkraft",
      "destination_url": "https://affkraft.com/themes",
      "occurred_at": "2026-03-19 14:20:05",
      "device_type": "mobile",
      "browser": "Safari",
      "os": "iOS",
      "country_code": "GB",
      "page_url": "https://yoursite.com/best-gambling-wp-themes/",
      "ip_hash": "b7e2d1...",
      "bot_detected": false,
      "bot_name": null
    }
  ],
  "meta": {
    "per_page": 100,
    "has_more": false,
    "last_id": 8801
  }
}
```

***

### GET /stats/links/{link_key}

Returns an aggregated summary for a single link.

**URL parameter:** `link_key` — the link's short key (e.g. `affkraft`).

**Query parameter:** `days` — number of days to include (e.g. `?days=30`). Pass `0` for all time. Defaults to `30`.

**Response:**

```json
{
  "data": {
    "total_clicks": 412,
    "total_impressions": 3840,
    "clicks_by_day": { "2026-03-18": 24, "2026-03-19": 31 },
    "by_device": { "desktop": 280, "mobile": 120, "tablet": 12 },
    "by_country": { "US": 180, "GB": 74, "CA": 60 },
    "by_browser": { "Chrome": 210, "Safari": 98 },
    "top_referrers": { "yoursite.com/best-gambling-wp-themes/": 140 }
  }
}
```

***

## Pagination

The links, clicks, and impressions endpoints use cursor-based pagination via `after_id`. To retrieve all records:

1. Make an initial request (no `after_id`)
2. If `meta.has_more` is `true`, make the next request with `after_id` set to `meta.last_id`
3. Repeat until `meta.has_more` is `false`

***

## Efficient Polling with Last-Modified

All endpoints include a `Last-Modified` header in their responses indicating the timestamp of the most recent event in the queried range.

On subsequent polls, send this value back as `If-Modified-Since`:

```
If-Modified-Since: Wed, 19 Mar 2026 14:22:11 GMT
```

If no new events exist, the server returns `304 Not Modified` with an empty body — saving bandwidth and processing time on both ends.

---

URL: https://docs.affkraft.com/nonaki/ai
Markdown: https://docs.affkraft.com/nonaki/ai.md

# Nonaki & AI

With Nonaki 2.1.0 you can manage your links from an AI chat. Ask Claude or
ChatGPT something like "which links are broken?" or "create a link called *bonus* that
goes to *affiliate URL*", and it does the work on your website for you.

This page explains how to set that up. If you are a developer using a coding
tool such as Claude Code, skip to
[Coding agents and developer tools](https://docs.affkraft.com/nonaki/ai#coding-agents-and-developer-tools).

***

## Manage your website from a chat with an AI agent

### How it works

An AI assistant doesn't log in to your dashboard and click around like you do.
Instead, your website gives it a list of specific tasks it is allowed to do,
such as "list links", "update a link" or "run the link checker". WordPress calls
these tasks **abilities**.

To make this work you need three things:

1. **Nonaki** provides the abilities for your links, tags, click and impression
   stats, the link checker and Nonaki settings. You choose which ones to offer
   on the **Nonaki → AI & Abilities** tab.
2. **"[MCP Adapter](https://wordpress.org/plugins/mcp-adapter/)"**, a free
   plugin, lets AI apps connect to your website and use those abilities.
3. **"[Enable Abilities for MCP](https://wordpress.org/plugins/enable-abilities-for-mcp/)"**,
   a free plugin, adds the sign-in. When you connect a chat app, you log in to
   your WordPress website and approve the connection, much like "Sign in with
   Google" on other websites.

The assistant then works as the WordPress user you signed in with. If that user
isn't allowed to do something, the assistant can't do it either. All Nonaki
abilities need an Administrator account, the same users who can open the
Nonaki screen.

> **Warning**
>
> AI abilities need WordPress 6.9 or newer. On older versions the
> **AI & Abilities** tab shows a notice; update WordPress to use them. The rest of
> Nonaki works on WordPress 6.0 and newer.
>
> Your website must also be online and use HTTPS, because the chat app connects
> to it over the internet. A local website, or a staging website behind a
> password, won't work.

### Set it up

1. **Install the plugins.** Go to **Nonaki** and open the **AI & Abilities** tab
   in the header. The **Status** box has buttons to install and activate both
   plugins.
2. **Choose what the assistant can do.** On the same tab, turn on **Expose
   Nonaki abilities to AI agents**, then choose the groups you want and click
   **Save Changes**. The default groups let the assistant read and edit links
   and tags, run the link checker and change Nonaki settings, but not move
   links to the trash or delete tags.
3. **Turn on sign-in.** Go to **Settings → WP Abilities**, open the
   **Connection** tab and turn on the OAuth connector.
4. **Connect your chat app.** In your chat app, add a *custom connector* and
   paste your website address. You'll be sent to your WordPress login page:
   sign in with an Administrator account and approve.
5. **Try it.** Start a new chat, make sure the connector is switched on for it,
   and ask "list my five most recent Nonaki links".

Where to add a custom connector depends on the app. Menu names change often, so
treat these as a guide:

| App | Where |
| --- | --- |
| Claude | **Settings → Connectors → Add custom connector** |
| ChatGPT | Turn on Developer Mode in **Settings → Apps & Connectors → Advanced settings**, then create a connector with your website address and OAuth sign-in. Paid plans only, at the time of writing. |
| Gemini | **Settings → Connected Apps → Add a custom app**. Available to personal accounts in the US only, at the time of writing. |

> **Tip**
>
> "Enable Abilities for MCP" also comes with its own abilities for posts, pages,
> media and more. Nonaki doesn't need them, so turn on only the ones you want on
> its **Abilities** tab.

### The AI & Abilities tab

**Status** tells you whether everything is ready. A green tick means that part
is fine; a warning icon tells you what's missing, usually with a button to fix
it.

* **MCP Adapter** and **Chat app sign-in (OAuth)** show whether the two plugins
  are active. When MCP Adapter is active, its endpoint address is shown too.
* **Nonaki abilities** shows how many tasks the assistant can currently use,
  and from how many groups.
* **Hidden elsewhere** only appears if "Enable Abilities for MCP" has switched
  off some of Nonaki's abilities on its own screen. Turn them back on there if
  you want to use them.

**Ability Groups** starts with the main switch, **Expose Nonaki abilities to AI
agents**. It is off by default, and while it's off, Nonaki offers nothing to
assistants, whatever the other settings say. Once it's on, the groups appear
below it, each with a short description of what it allows.

**Individual abilities (advanced)** appears once the main switch is on. It is
collapsed by default: click it to open. Untick an ability to switch off just
that one inside a group you turned on. For example, you can let the assistant
edit links but not change the redirect slug. Two labels help you spot the
risky ones:

* **Cannot be undone** marks abilities whose changes are permanent, such as
  **Delete tag**.
* **Use with care** marks abilities with wide effects that you can still undo,
  such as **Set redirect slug**.

### Ability groups

"Who can use it" means which WordPress users the assistant can sign in as to
use that group.

| Group | What it can do | Abilities | Who can use it | Default |
| --- | --- | --- | --- | --- |
| Links: read | List and search links, view a link, list tags, and read click and impression stats. Read-only | `nonaki/list-links`, `nonaki/get-link`, `nonaki/list-tags`, `nonaki/get-link-stats`, `nonaki/list-link-clicks` | Administrators | On |
| Links: edit | Create and update links, add or remove tags on links, and create or rename tags | `nonaki/create-link`, `nonaki/update-link`, `nonaki/add-link-tags`, `nonaki/remove-link-tags`, `nonaki/create-tag`, `nonaki/update-tag` | Administrators | On |
| Link checker | Run the broken link checker and read its results | `nonaki/check-links`, `nonaki/get-link-check-results` | Administrators | On |
| Links: trash | Move links to the trash and restore them, and delete tags. Never deletes links permanently | `nonaki/trash-link`, `nonaki/restore-link`, `nonaki/delete-tag` | Administrators | Off |
| Nonaki settings | Read and update Nonaki settings: the redirect slug, GeoIP auto-update and the link checker | `nonaki/get-settings`, `nonaki/update-settings`, `nonaki/set-slug` | Administrators | On |

### The 19 abilities

| Ability | What it does |
| --- | --- |
| `nonaki/list-links` | Lists links with their key, destination URL, redirect type, link checker status, click and impression counts and tags. Filters by search text (matches the key or the destination URL), status (active or trashed), tag or link checker result, and sorts by date, key or clicks. Up to 100 links per page. |
| `nonaki/get-link` | Returns one link by ID, active or trashed, with its tags and counters. |
| `nonaki/list-tags` | Lists every link tag with its ID, name, slug and the number of links that have it. |
| `nonaki/get-link-stats` | Returns the analytics summary for one link over the last 7 to 365 days (30 by default) or all time: total clicks and impressions, daily clicks and impressions, and the top 10 devices, browsers, operating systems, countries, referrers and pages the link was viewed on. |
| `nonaki/list-link-clicks` | Lists the individual clicks on one link, newest first, with time, device type, browser, operating system, country and referrer. Also says how many clicks are still queued for processing; they appear within a few minutes. |
| `nonaki/create-link` | Creates an active link with a link key, destination URL, redirect type (301, 302 or 307; 302 by default) and tags. Fails if the link key is already used, also by a trashed link. |
| `nonaki/update-link` | Changes a link's key, destination URL, redirect type or tags. Only the values passed change, but a new tag list replaces the link's whole tag list. |
| `nonaki/add-link-tags` | Adds tags to one or more links (up to 500 at a time), keeping the tags they already have. |
| `nonaki/remove-link-tags` | Removes tags from one or more links (up to 500 at a time). The tags themselves are kept. |
| `nonaki/create-tag` | Creates a link tag. Fails if a tag with the same slug already exists. |
| `nonaki/update-tag` | Renames a link tag; its slug follows the new name. Links keep the tag. |
| `nonaki/check-links` | Checks the destination URL of every active link now and marks each one `ok` or `broken`, and returns how many are newly broken. |
| `nonaki/get-link-check-results` | Returns when the link checker last ran, whether the daily check is on, and the active links it found broken (or `ok`, or not checked yet). |
| `nonaki/trash-link` | Moves a link to the trash. A trashed link stops redirecting until it is restored. Its stats are kept. |
| `nonaki/restore-link` | Restores a trashed link so it redirects again. |
| `nonaki/delete-tag` | Permanently deletes a link tag and removes it from every link. The links themselves are kept. This cannot be undone. |
| `nonaki/get-settings` | Returns the redirect slug (and whether it is fixed in code), the GeoIP auto-update and link checker switches, whether a MaxMind license key is set, the GeoIP database status, and when the link checker last ran. |
| `nonaki/update-settings` | Turns GeoIP auto-update, the daily link checker and its email on or off. Only the settings passed change. |
| `nonaki/set-slug` | Changes the redirect slug, the path in front of every link key. Fails when the slug is fixed in code by the `nonaki_slug` filter. |

### Keeping it safe

* **Start with the default groups** and turn on more only when you need them.
  Moving links to the trash and deleting tags are off by default.
* **Links are never deleted for good.** "Trash link" only moves a link to the
  [Trash](https://docs.affkraft.com/nonaki/links#trash), where you can restore it, and its stats are
  kept. Deleting a tag, however, can't be undone (the links themselves are
  kept).
* **Some things stay in the dashboard only.** The assistant can't permanently
  delete links, import or export links, or clear analytics data.
* **Your keys stay private.** The assistant can't read or change your Links and
  Stats API keys or your MaxMind license key, only whether a MaxMind key is set.
* **Some changes affect your public links.** Changing a link's key changes its
  public URL, so old links to it stop working. Changing the redirect slug
  changes the URL of every link at once, and nothing redirects the old slug, so
  old links stop working until you set the slug back.
* **Ask to see changes first**, especially for bulk edits: "show me the changes
  before saving".

> **Tip**
>
> `nonaki/check-links` checks every active link in one go, waiting up to 10
> seconds for each destination to answer. On a website with many links it can
> take a while, so give it time, or ask for the latest results with "which links
> did the link checker find broken?" instead. The daily check is described on the
> [Link Checker](https://docs.affkraft.com/nonaki/link-checker) page.

### Things you can ask

* "Which of my links are broken?"
* "Run the link checker and tell me what's newly broken."
* "Create a link with the key *bonus* that goes to *affiliate URL*, with a 301
  redirect."
* "Change the destination of the *bonus* link to *new affiliate URL*."
* "Tag every link that points to *example.com* with *casino*."
* "Which links had the most clicks in the last 30 days, and from which
  countries?"
* "Show me the last 20 clicks on the *bonus* link."
* "Turn on the daily link checker email."

***

## Coding agents and developer tools

Tools such as Claude Code, Codex or Cursor don't need the chat-app sign-in, so
"Enable Abilities for MCP" isn't required. You still turn on the abilities in
**Nonaki → AI & Abilities**.

### MCP over HTTP

Needs the "MCP Adapter" plugin and a WordPress
[Application Password](https://developer.wordpress.org/advanced-administration/security/application-passwords/)
(**Users → Profile**) for an Administrator. The
`@automattic/mcp-wordpress-remote` proxy connects to the endpoint. For Claude
Code:

```bash
claude mcp add wordpress \
  --env WP_API_URL=https://example.com/wp-json/mcp/mcp-adapter-default-server \
  --env WP_API_USERNAME=your-user \
  --env WP_API_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
  -- npx -y @automattic/mcp-wordpress-remote@latest
```

### MCP over WP-CLI

On a local site, or over SSH, you can skip HTTP and run the MCP server through
WP-CLI (STDIO):

```bash
wp mcp-adapter list
wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin
```

### WordPress REST API

Abilities with REST enabled are also listed by WordPress itself at
`/wp-json/wp-abilities/v1/abilities`. Nonaki's abilities are in the `nonaki`
category. For the regular Nonaki REST API with API keys, see
[Integrations](https://docs.affkraft.com/nonaki/integrations).

### Letting other roles use the abilities

Every Nonaki ability needs the `manage_options` capability. To hand a group to
a lower role, use the `nonaki_ability_capability` filter. It receives the
capability and the group key (`read`, `edit`, `check`, `trash` or `settings`).
For example, to let Editors read links and stats:

```php
add_filter('nonaki_ability_capability', function ($capability, $group) {
    return $group === 'read' ? 'edit_pages' : $capability;
}, 10, 2);
```

***

## AI writing helpers in the editor

The official WordPress AI plugin adds writing helpers inside the Block Editor,
such as titles, excerpts and alt text. It works alongside Nonaki and is a
different thing from managing your website from a chat assistant.

---

URL: https://docs.affkraft.com/nonaki/privacy
Markdown: https://docs.affkraft.com/nonaki/privacy.md

# Privacy & GDPR

This page describes what data Nonaki collects, how long it is kept, and what tools are available to manage it.

***

## What Data Is Collected

### Clicks

When a visitor follows one of your redirect links, Nonaki records:

* Timestamp
* Device type, browser, and operating system (derived from User-Agent)
* Country (from CDN headers if available, otherwise from GeoIP if configured)
* Referrer URL
* A hashed version of the visitor's IP address (see below)
* Whether the visitor was identified as a bot

### Impressions

When a page on your site containing a Nonaki link is viewed, Nonaki records:

* Timestamp
* Device type, browser, and operating system
* Country (from CDN headers if available, otherwise from GeoIP if configured)
* The URL of the page where the link appeared
* A hashed version of the visitor's IP address

***

## IP Address Handling

Raw IP addresses are stored temporarily in an internal processing queue and are deleted within approximately 5 minutes after the background processor runs.

For long-term storage, the IP address is converted to a one-way hash (SHA-256 with a site-specific salt). This hash cannot be reversed back to the original IP address. It is used only to deduplicate impressions within short time windows — it cannot be used to identify a visitor.

***

## What Is Not Stored

* Full IP addresses in analytics (only hashed)
* Cookies or browser fingerprints

***

## Your Responsibilities as a Site Owner

All data described on this page is collected by you, on your website, from your visitors. AffKraft does not receive, access, or store any of it — the plugin runs entirely within your WordPress installation.

As the site owner, you are the data controller under GDPR and similar regulations. You should:

* Disclose analytics tracking in your privacy policy
* Ensure your use of visitor data complies with the laws applicable to your site and audience

***

## Clearing Analytics Data

The `Clear All Analytics` button in **Nonaki** → **Settings** → **Analytics Data** permanently deletes all recorded clicks, impressions, and queue entries. This can be used to respond to a GDPR erasure request or to start fresh.

Individual link analytics are also deleted when a link is permanently force-deleted from the Trash.