Skip to main content

Link Previews for App Links: What Each Platform Reads and How to Test It

You paste your app's link into a chat. Other links unfold into a card with a picture, a title and a line of text. Yours stays a bare address, or shows the app store's card instead of your own.

The card is not built from the tap. A crawler (an automated client that fetches a page and reads its tags) asks for the address, and the platform draws what the crawler finds. This guide explains what that crawler gets from an app link, which tags each platform reads, and how to test a link as a crawler.

Why app links often show no preview

A deep link (a link that opens a screen inside an app) often goes through a link service: a short address that looks at the device and sends an iPhone to the App Store, an Android phone to Google Play, and a phone that has the app into the app.

A crawler is not a phone. It has no app installed and nobody tapping, whatever its user agent (the line of text a client sends to say what it is) looks like. A link service that treats it like any other visitor redirects it somewhere: a store, a fallback website, or a page meant for desktop browsers. A crawler that follows the redirect reads the tags of the page it ends on. Any card then describes the store listing or the fallback site, not the thing you linked to, and if that page has no usable tags there may be no card.

How far a crawler follows a link varies by platform. Apple's technote on rich previews for Messages says link previews follow server-side redirects, but do not follow meta redirects and do not run JavaScript. A link page that routes with a script and carries no tags of its own gives Messages nothing to read. Meta's sharing guide says that when a page has no Open Graph tags, its crawler guesses a title, a description and an image.

How a link service answers a crawler

The fix is for the link service to recognise crawlers by user agent and answer them itself. The crawler gets a small HTML page whose head holds the tags for this one link. There is no redirect, so the tags describe the link itself. No tap is counted either, because a crawler is not a person.

AdTo works this way. A request counts as a bot when its user agent matches a list of names such as facebookexternalhit, twitterbot, slackbot, whatsapp, linkedinbot and pinterestbot, or when it is a HEAD request (one that asks for headers only). A bot receives a 200 page of Open Graph tags with no redirect, and no click is recorded. A crawler the list does not know is routed as a visitor: it is redirected, or it gets the desktop page with a QR code.

The tags that matter

The platforms below read Open Graph, a set of meta tags defined at ogp.me. The protocol lists four required properties for every page: og:title, og:type, og:image and og:url. It lists og:description and og:site_name as optional.

TagWhat it gives the cardWhat AdTo's page puts there
og:titleThe headlineThe link's title, else the app's, else "Open in the app"
og:descriptionA sentence or two under the titleThe link's description, else the app's, else a generic line built from the destination
og:imageThe pictureThe link's image, else the app's. Left out when neither is set
og:urlThe address the card stands forThe link's own address, with no query string
og:typeThe kind of pagearticle when the title and the description are both yours, else website
og:site_nameThe site behind the pageThe app's name
twitter:cardWithout the large value, AdTo's check reports a small square picture on Xsummary_large_image when there is an image, else summary

For a link with its own preview, the head of the page carries these tags:

<meta property="og:title" content="The spring collection is here" />
<meta property="og:description" content="Open the Acme app to see what is new this season." />
<meta property="og:image" content="https://cdn.example.com/spring.jpg" />
<meta name="twitter:image" content="https://cdn.example.com/spring.jpg" />
<meta property="og:url" content="https://acme.adto.app/welcome" />
<meta property="og:type" content="article" />
<meta property="og:site_name" content="Acme" />
<meta name="twitter:card" content="summary_large_image" />

The platforms that publish their rules ask for much the same set:

PlatformWhat its documentation says it reads
Facebookog:url, og:title, og:description and og:image as the basic tags. Meta's crawler also serves Instagram and Messenger
LinkedInThe same four, which its help page says must exist
WhatsAppog:title, og:description and og:url, not empty, with og:image for the thumbnail
Messages on iPhone and MacOpen Graph tags. Apple advises keeping the brand out of og:title and putting it in og:site_name
SlackoEmbed, and Twitter Card or Open Graph tags, read by its link-expanding crawler

Where pictures fail

A card with a title and no picture usually means the page was read and the image was not. The crawler fetches the picture in a second request, from whichever host the image lives on. Four things go wrong there:

  • The image host refuses the crawler. AdTo's preview check counts an HTTP 401, 403 or 429 from the image host as a refusal. LinkedIn's help page says that when a valid image does not appear, the site may be blocking LinkedIn. Meta's crawler page recommends adding its crawler to your allow list.
  • The file is too large. AdTo's check flags a picture over 5 MB for X and LinkedIn, and over 8 MB for Facebook. LinkedIn (5 MB) and Meta (8 MB) publish their limits themselves.
  • The address is a page, not a picture. It answers with something other than an image, so there is nothing to draw.
  • The first share comes before the first fetch. Meta notes that its crawler has to see an image once before it can show it, so the first person to share a new link may get no picture. Running the link through its Sharing Debugger first avoids that.

AdTo's docs recommend a 1200 × 630 px JPG or PNG.

Pinterest: what makes a link eligible for an Article Rich Pin

A Rich Pin is a Pin that carries information taken from the page and kept in step with it. For the article kind, Pinterest's help page lists three Open Graph tags: og:title, og:description and og:type set to article. Its developer page strongly suggests og:site_name as well.

A link whose preview page carries those tags is eligible, and no more than that: Pinterest decides what it shows. Its help page describes an article as a page with text, such as a news story or a blog post, and a link's preview page is a set of tags and one line. The same page says content can take up to 24 hours to sync to a Pin.

In AdTo, the preview page says article only when the title and the description both come from you. With the generic copy it says website, and the preview check reports that Pinterest would save the link as a plain Pin. The check also reports a link with no image as having nothing to save as a Pin.

Search engines are a different case

Search crawlers fetch links too, and there you want the opposite. Some links are personal, such as an invite that carries its sender, and none of them belongs in search results.

The tool for that is noindex. Google's documentation describes a robots meta tag with the value noindex, which tells search engines that support the rule not to index the page. It adds that the crawler has to be able to fetch the page to see the tag, so a page blocked in robots.txt never shows its noindex.

AdTo serves search crawlers the same preview page with one extra line, <meta name="robots" content="noindex">. The fetchers that social and chat platforms use to draw a card get the page without it.

How to test before sharing, and why an old card can stick

Ask for the link as the crawler would:

  1. Fetch the link with a crawler's user agent. Use a normal GET request, because the tags are in the body.
    curl -s -i -A "facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)" https://acme.adto.app/welcome
  2. Read the status line. A 200 followed by og: tags is what you want. A 301 or 302 usually means the service took the crawler for a visitor. On AdTo, a 404 means the link does not exist, and a 410 means it is paused or expired.
  3. Fetch the image the same way. Use the address in og:image. You want a 200 and an image content type. Repeat for each platform you care about, because a host that lets one crawler in can refuse the next.
    curl -s -o /dev/null -w "%{http_code} %{content_type} %{size_download}\n" -A "Slackbot-LinkExpanding 1.0 (+https://api.slack.com/robots)" https://cdn.example.com/spring.jpg

The user agent in step 1 is the one Meta documents, and the one in step 3 is Slack's. Pinterest lists three, among them Mozilla/5.0 (compatible; Pinterestbot/1.0; +https://www.pinterest.com/bot.html).

A card that was right in the test can still be wrong in an old post, because platforms keep what they fetched. How long varies, and only some of them say, so test before the link goes out:

  • Facebook caches an image by its address and does not update it unless the address changes. To replace a picture, give it a new URL. The Sharing Debugger, which needs a Facebook login, shows the tags the crawler read and fetches the page again.
  • LinkedIn offers Post Inspector to refresh a link. The refresh applies to new posts only.
  • Slack caches what its crawler fetched for about 30 minutes.

Doing this with AdTo

AdTo is a hosted link service. Your links live at https://<username>.adto.app/<slug>, and each one answers crawlers with the preview page described above. The app's social sharing preview covers every link that has none of its own. A link can carry a custom preview, set in the link editor or through the og_title, og_description and og_image_url fields of the links API. The title and the description hold up to 150 characters each.

The link editor's Check the preview on each platform asks for the saved link with the crawler user agent AdTo keeps for each of Facebook, X, LinkedIn, Pinterest, Slack, Discord, WhatsApp, iMessage and Telegram, and fetches the image the same way. For each platform it draws the card and lists the issues.

Create an AdTo account to try it on a link of your own. The tags and their fallbacks are listed in Social previews and the QR page, and the editor is described in the Links screen guide.