Link preview metadata

Introduction

When people send messages containing links to web sites, Messages in iOS and macOS will automatically generate inline previews for the links. These previews rely on metadata from the page referenced by the link. If no metadata can be found, a generic link preview is generated as shown in Figure 1.

However, by adding a small amount of Open Graph metadata on your pages you can enable a much richer link preview as shown in Figure 2.

This is accomplished by including the following meta tags on the webpage:

Listing 1Open Graph meta tags included on //www.apple.com/iphone.

Enabling Link Previews

Below are additional tips on how to get great looking link previews in Messages.

Consistent metadata for all user agents

• Serve the same metadata to both mobile and desktop versions of the page.

• Clients shouldnt have to play User-Agent tricks to receive useful metadata.

Images in link previews

• Use og:image to include an image in your link preview. Images specified with this metadata will typically be displayed at a fairly large size so be sure that the image is representative of the page, includes interesting details, and is of high enough quality to display beautifully [especially important on retina screens].

• For lower quality images that wont display well at large size or for icons, use an apple-touch-icon instead.

• Provide a high-resolution icon in addition to any images. The link preview generation will look for an apple-touch-icon, favicon, or one specified by .

• Avoid text in images. Images will be displayed at varying sizes depending on context and device, potentially making text unreadably small or comically large. It is much better to keep the image graphical and to use other metadata tags for text. The text provided in the metadata is also accessible for people using VoiceOver.

Videos in link previews

• Putting a direct link to your video asset in the Open Graph metadata is better than referencing an embeddable video page. With the direct link to video, Messages will load and display fast, and use the system user interface for video playback.

• If the link preview machinery encounters a og:video or twitter:player:stream that points to a downloadable single media asset [for example, an MPEG-4 file] that can be played, it will attempt to download the video and automatically play it back.

• Video that can be streamed but not downloaded [such as HTTP Live Streams or QuickTime Reference Movies] will still play inline, but require the user to tap to start playback. Video that requires embedding HTML or plug-ins will not play inline.

Titles in link previews

• Use og:title to specify the title of your link preview.

• Titles should be short and sufficiently specific that different pages on the same site are distinguishable. For example, product pages should indicate the product name in the title; articles should provide the title of the article.

• Do not put the site name or other branding in the og:title. Doing so often leads to duplication of information between the title and other parts of the rich presentation, and is semantically incorrect. Use og:site_name for the site name instead.

Reachability

• The machinery that creates link previews will not follow redirects, nor run JavaScript, so metadata must be available on the page without either occurring. Server-side redirects are followed, however, and are a good alternative.

• Pages that sit behind authentication walls should still have meaningful metadata. This can be done without revealing any sensitive content.

• On pages that require authentication, the main resource should ideally provide metadata for the page behind the wall, not for the sign in page itself. Given the need for authentication, the metadata may not be as rich, but providing a title with at least as much context as the user could have gleaned from the raw URL should be feasible in many cases and would produce much better link previews than showing Sign In for every page behind the authentication wall.

Limits

• All limits are subject to change at any point in time; use these only as guidelines.

• Icons should be square, and at least 108px per side.

• Images should be at least 900px in width.

• Images less than 150px in width will not be used, or may be presented as icons.

• The main resource located at the link is limited to 1MB. The total size of sub-resources [the icons, images, and videos which are selected as most interesting] is limited to 10MB.

Other Resources

• The official Open Graph documentation

• Facebook's Open Graph Debugger