=== Burnpedia Image Save Button Analytics ===
Contributors: lalokupfer
Tags: pinterest, save button, image hover button, click analytics, image sharing
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Adds a save-to-Pinterest button to your post images on hover, and shows which images readers save. Free click analytics, no account needed.

== Description ==

*Burnpedia Image Save Button Analytics is not affiliated with, endorsed by or
sponsored by Pinterest, Inc. Pinterest is their trademark, named here only to
say where the button saves to.*

A reader is looking at a photograph in your post and would happily save it to
Pinterest. Most of the time nothing on the page invites them to, so they scroll
on.

This plugin puts a small **save button on the images in your posts**. It is an
image hover button: point at a picture and it fades in, press it and Pinterest's
own save window opens with your image, your headline and a link back to the post
already filled in. On a phone, where there is nothing to hover, it is simply
always there.

It also counts the presses, so you can see **which of your images readers
choose to save.** Every press is recorded here, on your own site, in your own
database, and shown to you as a plain table — this post, this many saves, this
month and all time.

= What you get =

* **A save button on every content image** — on hover on a desktop, always
  visible on a phone or a tablet.
* **A private count of every press**, per post, for the last 30 days and for all
  time, with a 30-day trend line.
* **The right file gets saved.** WordPress serves several sizes of every image;
  the button always hands over the largest one, not the small copy a phone
  happened to download.
* **Your headline and your link**, already in the save window.
* **You choose what the description says.** A box in the post editor sets the
  Pin description for every image in that post, so what a reader saves carries
  the sentence you wrote rather than alt text meant for a screen reader. Leave
  it empty and the alt text is used, exactly as before.
* **A hidden Pin image, if you make one.** Attach a tall image built for
  Pinterest — the sort with your headline written across it — and the save
  button hands Pinterest that picture instead of the photograph the reader
  pressed. Nobody sees it on the page. Set one per post, or none at all.
* **It stays out of the way** — it never appears on icons, avatars or emoji, it
  skips anything with the class `no-save`, and it respects Pinterest's own
  `data-pin-nopin` attribute.
* **It never fights another plugin.** If Pinterest's own Pin It button
  (`pinit.js`) is already on the page, this one steps aside rather than drawing a
  second button beside it.
* **Your own clicks do not count.** While you are logged in, pressing the button
  does not add to the number.

= Nothing here is locked =

The button, the counting and the analytics screen are free. Not a trial, not a
limited number of posts, not a watermark, not a "pro" upsell in the middle of the
table. No account is needed and nothing is ever sent anywhere.

= The optional extra, and where it comes from =

Everything above is the whole plugin. One further feature is optional, and it
needs an account with our own service, [Burnpedia](https://burnpedia.app) — a
Pinterest scheduling and analytics tool we run.

Paste a free API key from
[burnpedia.app](https://burnpedia.app/dashboard/api) into **Save Button →
Account** and the Analytics screen gains three more columns of **Pinterest
analytics** — impressions, saves and outbound clicks for **your own Pins** for
those same posts. It answers the question the click count cannot: the images
readers wanted to save, next to how the Pins you published yourself actually
performed.

A free account at [burnpedia.app](https://burnpedia.app) is enough to get one,
and you can connect this site to it in one press without copying a key at all.
Without a key the plugin makes no outbound request except that one connection,
which happens only when you press the button for it, and nothing on the screens
above changes. Exactly what is sent, and when, is listed under **External
services** below.

= What it does NOT claim to know =

When a reader saves your image, the Pin that gets made lives in **their**
account. Pinterest reports that Pin's impressions and saves to them, not to you,
so this plugin does not show those numbers and does not estimate them.

What it measures is the part it can measure honestly: **how many readers pressed
save on each image.** That is a demand signal about your own photographs, and it
is the one that tells you which kind to make more of. Those counts stay on your
server, they are private to you, and they are free.

= Fast, and quiet =

* One JavaScript file, deferred, with no jQuery and no framework — under 8 KB
  over the wire.
* One stylesheet, under 2 KB over the wire.
* **Zero external requests.** No font, no icon set, no tracker, no CDN.
* **No layout shift.** The buttons float above your images and are not inserted
  into your post's markup at all, so nothing on the page moves — including the
  full-width images that a wrapper element would quietly break on a block theme.
* No cookies, on either side.

= Works with what you already use =

Classic themes and block themes, the block editor and the classic editor,
galleries, captions, lazy loading and responsive images. Right-to-left sites get
the button on the correct side without configuring anything, and a full-width
image stays full width — the plugin never wraps your post content, which is what
breaks wide images on a block theme.

= Privacy =

No visitor data is collected: no IP address is stored; rate limiting keeps only a
short-lived salted hash that cannot be read back to an address and expires within
minutes. There is no cookie, no user agent, no referrer and no profile. What is
stored is a number per post, a number per day, and a number for each image on a
post. The image is identified by a short code this plugin works out from the
image's own web address, never by anything about the person who saved it.

== External services ==

This plugin is a client for **Burnpedia** (https://burnpedia.app), a Pinterest
scheduling service we operate. It is used for **one optional feature**: the three
extra columns on the Analytics screen showing how your own Pins for these posts
perform.

**Nothing is sent anywhere unless you ask for it.** With no API key saved and
the install count switched off — which is how the plugin arrives — it makes no
outbound request of any kind. There is no analytics, no phone-home you did not
switch on, no advertising and no third-party asset: every script and style in
this plugin is served from your own site, and the click counter talks to your own
site and nothing else.

There are two separate things you can switch on, and neither is on by default.
One is an API key, which unlocks the Pinterest columns. The other is the install
count below, which is not required for anything and unlocks nothing — it exists
only so we can tell how many sites use this plugin.

**Connecting this site in one press (optional).** On the **Account** screen you
can press **Connect this site to Burnpedia** instead of copying an API key by
hand. It is the only thing in the plugin that makes a request before a key
exists, and it happens only after an administrator presses that button:

* Your browser opens `https://burnpedia.app/connect/wordpress`, carrying this
  site's address and its title, so the approval screen can name the site you are
  about to connect. It also carries a random one-time request ID and a
  fingerprint of a secret that never leaves your server.
* After you approve it there, your site makes one
  `POST https://burnpedia.app/api/site-connect/claim` request, sending that
  request ID and the secret, and receives an API key which is saved for you. The
  key is never shown in your browser.
* The request expires after fifteen minutes and can be collected only once. If
  you press Cancel, or never approve it, nothing is sent and nothing is created.
* You never have to use it. Pasting a key by hand still works exactly as before,
  and is the way to connect a site that cannot reach the internet.

**The reader-click counting is not involved in any of this and never contacts
anyone**, with or without a key.

When a key **is** saved, these requests are made, and only these:

* `GET https://burnpedia.app/api/v1/me` — when an administrator opens the
  Analytics or Account screen, or presses **Check connection**. Sends: your API
  key. Receives: your plan, and whether a Pinterest account is connected.
* `GET https://burnpedia.app/api/v1/analytics/site` — when an administrator opens
  the Analytics screen. Sends: your API key and this website's domain name.
  Receives: impressions, saves and outbound clicks for the Pins you published
  through Burnpedia for this website, over the last 30 days.

* `POST https://burnpedia.app/api/v1/events/save-clicks` — at most once every
  twelve hours, when an administrator opens the Analytics screen. Sends: your API
  key, this website's address, and how many times readers pressed Save on each of
  the last 90 days — a date and a whole number, nothing else. Receives: how many
  days were recorded. It puts those counts beside your Pin results in your
  Burnpedia dashboard. **Nothing about any reader is in it.** The plugin stores
  no IP address, no user agent, no referrer and no cookie, so there is nothing
  about a visitor for it to send. Switch it off under **Save Button → Account**
  and the counts never leave your server.

**The install count (optional, off by default).** WordPress.org does not tell
plugin authors how many sites are running their plugin — for this plugin it
publishes no figure at all. If you switch this on under **Save Button →
Account**, this site sends a short report:

* `POST https://burnpedia.app/api/plugin-insights` — once when you switch it on,
  then at most once a week while an administrator is using wp-admin, once if you
  deactivate the plugin, and once if you delete it. Sends exactly nine things: a
  random ID generated on this site, which plugin and which version, which of
  those four events it is, your WordPress version, your PHP version, your site
  language, whether this is a multisite network, and whether an API key is saved
  (true or false — never the key). Receives: nothing your site uses.

**Your website address is not in that report and is never sent, so we cannot
tell which website you are.** The random ID is made up on your server and means
nothing outside it. Switch the setting off and the ID is deleted, so counting
stops and a later change of mind cannot be joined to it. It is off until you
choose it, no feature depends on it, and nothing about any reader or any logged-in
user is in it.

Every request above is made from your server, never from a reader's browser,
and every one happens only while an administrator is signed in to wp-admin — a
visitor reading your site can never cause any of them. Each also carries a header
naming the plugin and its version, so we can tell which version a request came
from.

Burnpedia's terms: https://burnpedia.app/terms
Burnpedia's privacy policy: https://burnpedia.app/privacy

**Pinterest itself is never contacted by this plugin.** The save button opens
Pinterest's own save dialog in the visitor's browser when the visitor clicks it,
exactly like following a link; the plugin sends nothing to Pinterest and loads
nothing from it.

Burnpedia is our own service and is not affiliated with Pinterest, Inc.

== Installation ==

1. Install and activate the plugin.
2. That is it — the button is already on the images in your posts, and readers
   can save to Pinterest in one press.
3. Open **Save Button** in the menu to see which images readers are saving.

To change where the button sits, how big it is, or which post types it appears
on, go to **Save Button → Button**.

The three extra Pinterest columns are optional. If you want them, go to **Save
Button → Account** and press **Connect this site to Burnpedia**. Approve it in
the tab that opens — a free account takes a moment to make if you do not have
one — and your site collects its own key. There is nothing to copy or paste.

If your site cannot reach the internet, or you would rather do it yourself, the
same screen still takes a key you paste in by hand.

== Frequently Asked Questions ==

= Do I need an account? =

No. The button, the counting and the whole analytics screen work with no account
of any kind, and nothing leaves your site.

A free Burnpedia account is needed for exactly one thing: the three columns
showing how **your own** Pins for those posts are doing on Pinterest.

= Do you collect any visitor data? =

No visitor data is collected: no IP address is stored; rate limiting keeps only a
short-lived salted hash that cannot be read back to an address and expires within
minutes. No cookie is set, no user agent or referrer is kept, and nothing about a
reader is ever sent off your server.

= Is this a Pin It button? =

It does the same job. Pinterest's original Pin It button was a script you loaded
from Pinterest; this is a save button your own site draws, so nothing is fetched
from Pinterest and nothing about your readers is sent anywhere. Pressing it opens
the same save window.

If you already run Pinterest's own Pin It button (`pinit.js`), this plugin
detects it and stays out of the way rather than putting two buttons on one image.

= Can I turn the hover off and show the button all the time? =

Yes — **Save Button → Button → When it shows**. Hover is the default on a
desktop because a button that is always visible sits on top of the photograph
you want people to look at. On phones and tablets it is always shown either way,
because there is no hovering with a finger.

= Why don't I see the button? =

The usual reasons, in the order they turn out to be true:

1. **A page cache has not been cleared yet.** Purge it and reload.
2. **Pinterest's own widget is on the page.** If `pinit.js` is loaded — often by
   a tag manager — this plugin steps aside rather than drawing a second button.
3. **The image is smaller than the minimum.** The default skips anything under
   200 pixels in either direction, which is what keeps buttons off icons and
   author photos. Lower it under **Save Button → Button**.
4. **The image, or something around it, carries an excluded class** — `no-save`,
   one you added yourself, or Pinterest's `data-pin-nopin` attribute.
5. **The post type is switched off**, or the theme prints the post body without
   running WordPress's own content filter, which some page builders do.

= Why is the click count zero? =

Almost always a security plugin. Several of them switch the WordPress REST API
off for logged-out visitors, and that is the path the count travels on — so the
button still works, and the number never moves.

There is a **Send a test click** button on the Analytics screen that sends one
real click along exactly the same path a reader's browser uses, without your
login. It answers the question in about a second.

= Does it slow my site down? =

One deferred JavaScript file of under 8 KB over the wire and one stylesheet
under 2 KB, both served from your own site, with no jQuery, no framework and no
external request at all. The buttons are drawn over your images rather than
inserted into them, so the page does not move when they appear.

= Will it change my posts? =

No. It never edits your content. The buttons are drawn in a layer above the page,
which is also why full-width images stay full width.

= Which image gets saved? =

The largest one your site offers. WordPress makes several sizes of every image
you upload, and a browser on a phone downloads a small one — saving that copy
would leave a phone-sized Pinterest image on somebody's board forever. This
plugin reads the whole set and hands over the biggest, so what people save is
always the sharp copy.

= Can I choose what the Pin description says? =

Yes. Every post has a **Save Button (Burnpedia)** box in the editor sidebar with
one field: the Pin description for that post's images. Whatever you type there is
what Pinterest fills in when a reader saves any image from the post.

Leave it empty and nothing changes — the image's own alt text is used, and then
the post title. An individual image that carries Pinterest's own
`data-pin-description` attribute keeps that, because it is a more specific
choice than a whole-post default.

The box appears for anyone who can publish that post type. It is not shown to
contributors, because the text goes out on a public Pin under your site's name.

= Can I use a separate image for Pinterest? =

Yes. Open a post, find the **Save Button (Burnpedia)** box and choose a **hidden
Pin image**. It is usually a tall graphic, often 1000 by 1500, with the headline
set across it — the shape that works in a Pinterest feed and would look wrong in
the middle of an article.

Readers never see it. When somebody presses the save button anywhere on that
post, Pinterest opens with that graphic rather than the photograph they pressed,
and with your Pin description. A copy of it is also placed in the page, hidden,
which is where Pinterest's own browser tools look for images to offer.

Two honest notes. Their browser does download it even though they never see it —
that is exactly what makes it findable, so only set one on posts where you want
it saved. And the count still records which photograph they pressed, because
"which picture makes people save" is worth knowing separately from what gets
saved.

= Can I stop it on certain images? =

Yes, four ways: add the class `no-save`, add `data-pin-nopin` to the image, add
your own class names under **Save Button → Button**, or raise the minimum image
size.

= Is my count exact? =

It is honest, and it is not a billing system. Presses are counted as they arrive,
with two limits that keep somebody from inflating it: no more than 30 clicks a
minute from one visitor, and no more than 2,000 a day on any one post. Your own
clicks, while you are logged in, are never counted.

= Can I turn a most-saved image into a Pin? =

If you also run our scheduling plugin, yes: every row in the table gets a
**Schedule a Pin** button that opens that post at the scheduling panel, so the
image readers are already saving is one click from being queued.

Nothing appears if you do not have that plugin. This one never suggests
installing anything.

= Does anything about my readers leave my site? =

No, and there is nothing that could. The plugin never stores an IP address, a
user agent, a referrer or a cookie, so no visitor detail exists here to be sent.

If you have connected a Burnpedia account, the plugin sends your **daily
totals** — this website's address, a date and a whole number per day — so those
counts can sit beside your Pin results in your dashboard. It goes at most once
every twelve hours, only while you are on the Analytics screen. You can switch it
off under **Save Button → Account**, and with no API key saved nothing is sent at
all.

= What happens if I delete the plugin? =

Everything it wrote is removed: the settings, the counts, the daily series and
the caches. Your posts and your images are not touched.

== Screenshots ==

1. The save button on a post image — it appears when a reader points at the
   picture, and it is always visible on a phone.
2. The same post on a phone, where the button stays on screen.
3. The Analytics screen: which posts readers save, a 30-day trend, and the
   "Your Pins on Pinterest" columns a free account fills in.
4. Button settings — where it sits, how big it is, and which images to skip.
5. The Account screen, where the optional free connection lives.
6. The hidden Pin image on a post: a tall graphic readers never see, which the
   save button hands to Pinterest instead of the photograph they pressed.

== Changelog ==

= 1.8.0 =
* New: a **hidden Pin image** per post. Attach the tall, headline-across-it
  graphic you made for Pinterest, and the save button hands Pinterest that
  picture instead of the photograph the reader pressed. Readers never see it on
  the page.
* Pinterest's own `data-pin-media` attribute is honoured too, so a single image
  can override the whole post.
* The Pin description follows the graphic: when one is set, the pressed
  photograph's alt text is no longer offered, because it describes a different
  picture.
* The click count is unchanged — it still records which photograph a reader
  pressed, which is a different question from what got saved.
* Note that readers' browsers do download the hidden image, which is what makes
  it findable. It is only ever added to posts where you set one.

= 1.7.0 =
* New: the Analytics screen now shows **which image** on a post readers saved,
  not just how many saves the post got. Open "Saved images" under any post title
  for a thumbnail of each one and its own count.
* On a roundup or a gallery post this answers the question the old number could
  not: of the six photos on the page, which one do readers actually want?
* Counts recorded before this update stay on the post as a whole. They are
  reported separately rather than split between images, because nothing can know
  after the fact which image an old save was on.

= 1.6.0 =
* New: if you are switching from **jQuery Pin It Button for Images**, the Button
  screen now offers to copy its settings across — where the button sits, whether
  it shows on hover, which classes to skip and the minimum image size. One press,
  and you can say no.
* It never changes or switches off that plugin: it only reads its settings, and
  it tells you plainly which of them have no equivalent here rather than quietly
  dropping them.
* A setting you have already changed yourself is never overwritten.

= 1.5.0 =
* New: **Connect this site to Burnpedia** — one button on the Account screen.
  Approve it in the tab that opens and your site collects its own API key. There
  is nothing to copy, nothing to paste, and the key is never shown in a browser.
* Pasting a key by hand still works exactly as before, and is still the way to
  connect a site that cannot reach the internet.
* The button, the counting and the analytics table are unchanged, still free,
  and still contact nobody.

= 1.4.0 =
* New: an optional install count under Save Button → Account. WordPress.org
  publishes no install figure for this plugin, so we genuinely cannot tell how
  many sites use it. Switch this on and your site sends a random ID once a week
  so it can be counted. Your website address is never sent. It is off unless you
  turn it on, nothing depends on it, and turning it off deletes the ID.

= 1.3.0 =
* If you also run our scheduling plugin, every row in the Analytics table now
  has a **Schedule a Pin** button that opens that post straight at the panel
  where you queue it. The image your readers keep saving is one click from being
  a Pin you posted on purpose.
* Nothing changes, and nothing is shown, on a site without that plugin.

= 1.2.0 =
* Your daily click totals can now appear in your Burnpedia dashboard, beside
  what your own Pins for those pages earned — the first time both halves of that
  picture have been in one place. Optional, off with one tick under **Save
  Button → Account**, and it sends a date and a number and nothing else.
* Documented the new request under **External services**.

= 1.1.0 =
* New: a **Pin description** box in the post editor. It sets the description
  Pinterest opens with when a reader saves any image from that post, so you are
  no longer limited to alt text written for a screen reader. Leave it empty and
  the previous behaviour is unchanged.
* The plugin's internal version number had been left at 1.0.0 through the 1.0.1
  release, so browsers kept serving the old copy of the stylesheet after an
  update. Fixed, and a test now compares the two.

= 1.0.1 =
* Renamed the plugin to Burnpedia Image Save Button Analytics.
* Rewrote the description: removed comparative wording, and said plainly what
  the optional Burnpedia connection adds and where to get a key.

= 1.0.0 =
* First release.
