Here's a doc we never published while I was at Pinterest. Some or all of it may be useful; please keep in mind that I've been ex-Pinterest since March 2022 and cannot help if it doesn't work.
I apologize in advance for the chirpy Pinterest editorial tone throughout; it's a Thing there.
Hi, all. Kent Brewster here, oldest surviving engineer at Pinterest. For the past ten years we've been working on a handful of things that help people who love Pinterest find new inspiration from the Web and share it as easily as possible.
These things are:
- Browser extensions and mobile sharing helpers that Pinners can run on their devices, to help find and add new material to Pinterest.
- Buttons and widgets that add a little bit of Pinterest to sites all over the world.
- Utilities that look at all the images on a page, find the best ones, and show them to Pinners, hopefully with the best ones on top for easy saving.
- Markup conventions -- including meta tags and data attributes for images -- that will help Pinterest do the right thing when a Pinner wants to save a page.
As a group these things make up what we're calling Offsite Engagement: code and instructions supplied by Pinterest that's intended to run (or at least fail gracefully, for browsers that can't use Pinterest) on every other domain in the world.
This document shows some simple steps that you can take to increase your reach on Pinterest, using good Web design principals and the tools listed above.
Much of what's here has been said before on different iterations of the Pinterest engineering, partner, developer, and consumer blogs; please consider this the definitive version, one which we promise will be kept online and maintained.
- What's the best way to control how my content looks and acts on Pinterest?
- What if I don't want to bother with pinning all my pages?
- What's the best way to remind Pinners that they should save my stuff to Pinterest?
- Super bonus material: questions about Save buttons whose answers all start with "yes."
Put it on Pinterest yourself! Whenever you make a fresh post, do this:
- Create an image optimized for Pinterest. It's going to be 600px wide by 900px tall--portrait, not landscape--and it might feature your logo or a written caption superimposed over the main image.
- Write a great default description. Ideally the description will say what's in the image and what Pinners might want to remind themselves to do about it.
- Include a canonical URL. This should be a permanent link, not a redirector, and should not include a bunch of tracking parameters or affiliate links. (Why? Because saves to Pinterest are counted on unique URLs and you want your save count for each Pin to reflect the actual number as accurately as possible.)
Save your new page to Pinterest with your optimized image, default description, and canonical URL. Visit your new Pin and note its ID, which is the very long number after /pin/ in the URL, like this:
https://www.pinterest.com/pin/8675309/
Then go back to your page, open it up, and add META tags for pin:media and pin:id to the HEAD, like this:
<meta property="pin:media"
content="https://yourcdn.com/your_directory/optimized_image.png" />
<meta property="pin:id"
content="8675309" />
On all other pages in your domain where a thumbnail image is linked to the page you saved on Pinterest -- search results, catalog pages, blog indexes, or More Like This lists -- add the data-pin-id parameter to the image that links to the page, like this:
<a href="https://yourdomain.com/your_canonical_url">
<img
src="https://yourcdn.com/your_directory/image_thumb.png"
data-pin-id="8675309"
/>
</a>
- If Pinterest finds a pin ID when we're looking at IMG or META tags, we will create a repin of your original pin, instead of a new pin.
- Since you control the original pin, the image, link, and default description will be exactly what you say it should be.
- From the canonical page (the one with the META tags) our pinnable-thing-finder will skip right to the pin create form, with your repin cued up and ready to save, instead of showing a possibly-distracting grid of all the images on the page.
- From any other page, our pinnable-thing-finder will show your optimized image in the thumbnail grid, promoted above other images without pin IDs. These will also repin your original when chosen.
- You will be notified of the repin by Pinterest, via whatever channels you have selected.
The usual guidelines for getting organic content onto any network apply. They are:
Write a great description. This makes a huge difference in impressions and clicks, and the initial pin create process. Important: pin descriptions are not the same as what you'd put in an ALT attribute (which is for accessibility, and should describe what is in the picture) or the TITLE attribute, which usually contains the title of the page. "Cupcakes" or "Appalachian Trail" may accurately describe what's in the picture, but "Make these amazing red velvet cupcakes" or "Hike the Appalachian Trail" are much better descriptions for Pinners, since they talk about what they might do in the future.
There's lots more to say about creating great descriptions for Pinterest; more on that later.
Please consider adding a default description just for Pinterest, with data-pin-description:
<img
src="https://yourcdn.com/your_directory/image_thumb.png"
data-pin-description="Boil an egg without having the peel stick."
/>
You can also do this with a META in the HEAD of your page:
<meta property="pin:description"
content="Boil an egg without having the peel stick." />
Specify the right URL. If the image appears in your blog index, please consider giving us the canonical URL, with data-pin-url. Otherwise we will save the page we find the image on, which leads to a lot of saves for blog indexes that don't actually show the image when Pinners click through:
<img
src="https://yourcdn.com/your_directory/image_thumb.png"
data-pin-description="How to boil an egg without having the peel stick."
data-pin-url="https://yoursite.com/how-to-boil-an-egg/"
/>
Use the best image, or create one just for Pinterest. If a thumbnail of your image appears in search results or catalog pages, please consider adding a pointer to the the full-sized image, with data-pin-media. Otherwise the pinnable-thing-finder will only see the thumbnail, which might be too small to save:
<img
src="https://yourcdn.com/your_directory/image_thumb.png"
data-pin-media="https://yourcdn.com/your_directory/image_fullsized.png"
data-pin-description="How to boil an egg without having the peel stick."
data-pin-url="https://yoursite.com/how-to-boil-an-egg/"
/>
Add a Save button! It's super easy!
Add the following code snippet, as close to the bottom of your tag as possible. For best results, do this inside a template, so you can modify it easily later for all pages.
<script async defer
data-pin-hover="true"
src="//assets.pinterest.com/js/pinit.js"></script>
The Image Hover Save Button will cause Save buttons to appear over images on the page that are large enough to be saved to Pinterest when the browser mouses over them. The default installation shown above creates a twenty-pixel-high button that says Save in whatever language the browser accepts.
If you'd like a taller button, add data-pin-tall="true", like this:
<script async defer data-pin-hover="true"
data-pin-tall="true"
src="//assets.pinterest.com/js/pinit.js"></script>
If you'd like your buttons to only show the round Pinterest logo and not the localized word Save, add data-pin-round="true", like this:
<script async defer
data-pin-hover="true"
data-pin-round="true"
src="//assets.pinterest.com/js/pinit.js"></script>
Sure! Both options may also be used at once, like this:
<script async defer
data-pin-hover="true"
data-pin-tall="true"
data-pin-round="true"
src="//assets.pinterest.com/js/pinit.js"></script>
... to make a large round Pinterest logo button.
As of this writing about 67% of the browsing population uses a mobile device with a touchscreen. Image hover Save buttons don't work for touchscreens because they don't know what you're doing until you actually touch the screen.
When the Image Hover Save Button is enabled, mobile browsers will see the Save button over the image that overlaps the vertical middle of the screen. In cases where two or more images both overlap the middle of the screen, the button will show over the image closest to the last touch.
If you leave the default installation alone you'll get a much higher number of pins. If that sticky button turns out to be a serious problem you can turn it off by adding data-pin-sticky="false" to your call to pinit.js, like this:
<script async defer
data-pin-hover="true"
data-pin-sticky="false"
src="//assets.pinterest.com/js/pinit.js"></script>
Sticky buttons are live worldwide, after an extensive testing period.
Once you're running pinit.js you can add visible, persistent Save buttons anywhere you want. Just add a link to our pop-up Save form, like this:
<a
data-pin-do="buttonBookmark"
href="https://www.pinterest.com/pin/create/button/"
></a>
If you have not already done so, don't forget to call pinit.js, as close to the end of your tag as possible:
<script async defer src="//assets.pinterest.com/js/pinit.js"></script>
When pinit.js runs it will look for links to the pin create form. If the browser taps one of these and it's decorated with data-pin-do="buttonBookmark", pinit.js will import and run a second script, pinmarklet.js, directly from our domain. Pinmarklet.js is the exact same script our mobile applications and browser extensions run to discover everything on the page that can be saved to Pinterest.
Yes. Just add data-pin-hover="true" to your call to pinit.js, exactly as listed above.
Yes, and that's a really good idea, because when Pinners see the inline P button and it's not over an image, they tend to think that it's a link to your Pinterest profile and not a Save button. Here's how to get tall round Image Hover buttons over each image and one regular-sized Save button, on the same page:
<script async defer
data-pin-hover="true"
data-pin-tall="true"
data-pin-round="true"
src="//assets.pinterest.com/js/pinit.js"></script>
Paste your Any Image Save button where you want it to appear, with data-pin-round="false" and data-pin-tall="false" for this link only:
<a
data-pin-do="buttonBookmark"
data-pin-round="false"
data-pin-tall="false"
href="https://www.pinterest.com/pin/create/button/"
></a>
Yes. To do this, set data-pin-custom="true" on the link, like this:
<a
data-pin-do="buttonBookmark"
data-pin-custom="true"
href="https://www.pinterest.com/pin/create/button/"
></a>
When pinit.js sees data-pin-custom="true" it will leave any HTML or CSS associated with the link alone, so you can style as needed.
Here's an old-school image-wrapped-in-a-link button:
<a
data-pin-do="buttonBookmark"
data-pin-custom="true"
href="https://www.pinterest.com/pin/create/button/"
><img src="fancy_pinit_button.jpg" /></a>
Here's a link styled by class name social pinterest. In CSS you'd need rules for social, which might be "show a clickable inline-block-styled thing, 32px by 32px," and pinterest, which might be "in addition to the rules specified in social, add a fancy shiny Pinterest logo for the background image."
<a
class="social pinterest"
data-pin-do="buttonBookmark"
data-pin-custom="true"
href="https://www.pinterest.com/pin/create/button/"
></a>
In both of these cases, pinit.js will add an event listener to the existing link, to open the pin create form. All existing structure, style, or event listeners will be left alone.
Yes, but we recommend using Image Hover and Any Image buttons instead. (Why? Because the markup gets complicated and you'll need to remember to maintain it, potentially forever.)
For help making single-image Save buttons, please visit the Widget Builder.
Yes, just add data-pin-count="above" or data-pin-count="beside" to the button you want to show pin counts.
- Pin counts will only show for Save buttons, not round buttons or hovering / sticky buttons.
- Counts are displayed for unique URLs saved to Pinterest. If
- Under normal circumstances, counts will be rendered for the current URL, which could include referrer parameters that might be saved to Pinterest.
- To show the count for a canonical URL (strongly recommended!) please specify it like this:
data-pin-url="http://yourdomain.com/your_canonical_url/"