# WordPress plugin

> Install Nvivio on WordPress without touching your theme, leave out administrators, show the Nvivio badge, and see your numbers on the WordPress dashboard.

The Nvivio plugin adds your site's script to every page of a WordPress site, can show the Nvivio badge with your referral link, and shows your visitors, pageviews and top pages on the WordPress dashboard. It needs WordPress 6.5 or later and PHP 8.1 or later.

## Install the plugin

1. [Download the plugin](https://nvivio.com/downloads/nvivio-wordpress.zip) (a zip of the latest version).
2. In WordPress, go to **Plugins › Add New Plugin › Upload Plugin**, choose the zip and activate it.
3. In Nvivio, open **Settings › Installation** and copy the line, or only the site code (`NV-` and seven characters).
4. In WordPress, paste it under **Settings › Nvivio** and save.

The plugin keeps the site code and puts the line from the installation page in the `<head>` of every page:

```html
<script defer src="https://nviv.io/js/NV-XXXXXXX.js"></script>
```

A typo in the code is caught when you save: the last character of every site code is a check character ([The site code](https://nvivio.com/docs/script#the-site-code)). To update the plugin, upload the new zip the same way; WordPress replaces the old version and keeps your settings.

## Check that it works

Logged-in administrators are not counted by default, so open your site in a private window. Nvivio's installation page switches to **It works** as soon as the visit arrives ([Check that it works](https://nvivio.com/docs/install#check-that-it-works)); the link **Check in Nvivio that it works** under the site code opens it.

A page cache (WP Rocket, LiteSpeed or your host's) can keep serving pages without the script: empty it once after installing.

## Settings

| Setting | What it does |
|---|---|
| Site code | The site's code, or the whole line pasted from the installation page. Below it, the plugin shows the line it puts on every page. |
| Administrators | **Do not count logged-in administrators**, on by default: visits by anyone who can manage the site are left out. |
| Early calls | Adds the [queue for early calls](https://nvivio.com/docs/script#early-calls) above the script, for a theme or plugin that calls `nvivio.track()` or `nvivio.consent()` before the script has loaded. |
| Cookie mode | Adds `data-consent="none"`: in [cookie mode](https://nvivio.com/docs/privacy#with-one-cookie-optional) the cookie is set right away. Only where you do not need consent. |
| Address for events | Adds `data-api`, for a proxy on your own domain such as `/stats/e`. Leave it empty to send events to nviv.io. |
| API key | For the dashboard widget, see below. |

What the script measures (outbound links, downloads, hash routes) stays in Nvivio, under **Settings › What the script measures**, as for every site ([What the script measures](https://nvivio.com/docs/settings#what-the-script-measures)).

## Your numbers on the WordPress dashboard

With an API key, the widget **Nvivio** on the WordPress dashboard shows:

- visitors and pageviews for **Today**, **7 days** or **30 days**, with the change from the period before;
- visitors per hour (today) or per day, as bars;
- the five most viewed pages;
- who is online now;
- a link to the site in Nvivio.

To connect it, make a key with the scope `read` in Nvivio, in the user menu › **API and AI assistants** ([Authentication](https://nvivio.com/docs/api#authentication)), and paste it under **Settings › Nvivio**. **Connection** then says which site the key reaches.

- **The key stays on your server.** WordPress asks `https://nvivio.com/v1` for the numbers itself (`stats`, `timeseries`, `breakdown` and `sites/live`) and never sends the key to a browser. Once saved, the key is not shown again, only its last four characters.
- **Answers are kept for five minutes**, who is online for one, so a busy dashboard uses few of your plan's [requests an hour](https://nvivio.com/docs/api#limits). Changing the site code or the key forgets them.
- **The API comes with Starter and up.** On a plan without an API, the widget says so and links to the plans; the script keeps counting on every plan ([The API](https://nvivio.com/docs/plans#the-api)).
- Only administrators see the widget. Each person's last period is remembered.

Without a key, the plugin only adds the script, and the widget links to your numbers in Nvivio.

## The badge and referrals

Under **Settings › Nvivio › Badge and referrals**, **Show the Nvivio badge on every page** puts [the Nvivio badge](https://nvivio.com/docs/plans#the-nvivio-badge-and-referrals) on your site without pasting code: "Privacy-friendly analytics by Nvivio" in the language of the page, linking to Nvivio with your site as the referral. While Nvivio sees it, Free counts more pageviews and events and a paid plan pays less, and whoever signs up through it and takes a paid plan gets free time, and so do you.

- **Look:** a text link in your theme's own font and colours, small or standard, light or dark, with or without the Nvivio ring.
- **Place:** at the bottom of every page, or in the bottom right corner. To put it somewhere else, for example in your theme's footer, add the shortcode `[nvivio_badge]` there (a Shortcode block in the site editor works too); the badge then shows there, once per page. A text link always goes at the bottom.
- The plugin adds the code from Badge and referrals in Nvivio: `badge.js` with your site code, in the footer of the page. Unlike the script, administrators see it too: it says nothing about who looks at it.
- **Switch it on in Nvivio too**, in the user menu › **Badge and referrals**: only then does it count. With an API key, the plugin says whether it is on and when and where Nvivio last saw it, on the settings page and at the bottom of the dashboard widget.
- **Your referral link** is under the badge settings, to share yourself: whoever signs up through it counts as your referral too. With an API key, the plugin shows how many signed up through your badge or link, how many of them pay, and the months you earned.

## Languages

The plugin speaks English and Dutch, in the language each WordPress user chose. The messages that come from Nvivio itself, such as an error of the API, follow that language too, in the 24 EU languages.

## For developers

- `nvivio_print_script`: whether the script goes on a page. To leave out every logged-in user: `add_filter( 'nvivio_print_script', fn( $print ) => $print && ! is_user_logged_in() );`
- `nvivio_widget_capability`: who sees the widget, `manage_options` by default; `edit_others_posts` lets editors see it too.
- The script is added with `wp_enqueue_script` (handle `nvivio`), so a plugin that adds a nonce for a [Content-Security-Policy](https://nvivio.com/docs/install#the-line) can add it. WordPress's own `id` and version are left off: the tag is the line from the installation page.
- `NVIVIO_SCRIPT_ORIGIN` and `NVIVIO_API_BASE` in `wp-config.php` point the plugin at another copy of Nvivio, for development.
- Deleting the plugin removes its settings, its key and its cached answers.