Permalink
Switch branches/tags
Find file Copy path
264 lines (217 sloc) 9.18 KB

amp-social-share

[TOC]

Description Displays a social share button.
Required Script
<script async custom-element="amp-social-share" src="https://cdn.ampproject.org/v0/amp-social-share-0.1.js"></script>
Supported Layouts container, fill, fixed, fixed-height, flex-item, nodisplay, responsive
Examples See AMP By Example's amp-social-share example.

Overview

The amp-social-share component displays a social share button for various social platform providers.

Examples

Example: Basic social share button

The share button guesses some defaults for you for some pre-configured providers. It assumes that the current document canonical url is the URL you want to share and the page title is the text you want to share.

<amp-social-share type="twitter"></amp-social-share>

Example: Passing parameters

When you want to pass parameters to the share endpoint, you can specify data-param-<attribute> that will be appended to the share endpoint.

<amp-social-share type="linkedin" width="60" height="44"
  data-param-text="Hello world"
  data-param-url="https://example.com/">
</amp-social-share>

Linkedin is one of the pre-configured providers, so you do not need to provide the data-share-endpoint attribute.

Attributes

type (required)

Selects a provider type. This is required for both pre-configured and non-configured providers.

data-target

Specifies the target in which to open the target. The default is _blank for all cases other than email/SMS on iOS, in which case the target is set to _top.

Please note that we only suggest using this override for email.

data-share-endpoint

This attribute is required for non-configured providers.

Some popular providers have pre-configured share endpoints. For details, see the Pre-configured Providers section. For non-configured providers, you'll need to specify the share endpoint.

data-param-*

All data-param-* prefixed attributes are turned into URL parameters and passed to the share endpoint.

Pre-configured providers

The amp-social-share component provides some pre-configured providers that know their sharing endpoints as well as some default parameters.

Provider Type Parameters
Web Share API (triggers OS share dialog) system
  • data-param-text: optional, defaults to: "Current page title"
  • data-mode: optional, if set to replace, all other share options are removed.
Email email
  • data-param-subject: optional, defaults to: Current page title
  • data-param-body: optional, defaults to: rel=canonical URL
  • data-param-recipient: optional, defaults to: '' (empty string)
Facebook facebook
  • data-param-app_id: required, defaults to: none. This parameter is the Facebook app_id that's required for the Facebook Share dialog.
  • data-param-href: optional, defaults to: rel=canonical URL
  • data-param-quote: optional. Can be used to share a quote or text.
LinkedIn linkedin
  • data-param-url: optional, defaults to: rel=canonical URL
Pinterest pinterest
  • data-param-media: optional (but highly recommended to be set), defaults to: none. Url for the media to be shared on Pinterest. If not set, the end user will be requested to upload a media by Pinterest.
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-description: optional, defaults to: Current page title
G+ gplus
  • data-param-url: optional, defaults to: rel=canonical URL
Tumblr tumblr
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-text: optional, defaults to: Current page title
Twitter twitter
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-text: optional, defaults to: Current page title
Whatsapp whatsapp
  • data-param-text: optional, defaults to: "Current page title - current page URL"
LINE line
  • data-param-url: optional, defaults to: rel=canonical URL
  • data-param-text: optional, defaults to: Current page title
SMS sms
  • data-param-body: optional, defaults to: rel=title - rel=canonical URL

Non-configured providers

In addition to pre-configured providers, you can use non-configured providers by specifying additional attributes in the amp-social-share component.

Example: Creating a share button for a non-configured provider

The following example creates a share button through Facebook Messenger by setting the data-share-endpoint attribute to the correct endpoint for the Facebook Messenger custom protocol.

<amp-social-share type="facebookmessenger"
    data-share-endpoint="fb-messenger://share"
    data-param-text="Check out this article: TITLE - CANONICAL_URL">
</amp-social-share>

As these providers are not pre-configured, you'll need to create the appropriate button image and styles for the provider.

Styles

Default Styles

By default, amp-social-share includes some popular pre-configured providers. Buttons for these providers are styled with the provider's official color and logo. The default width is 60px, and the default height is 44px.

{% call callout('Tip', type='success') %} Visit AMP Start for responsive, pre-styled share links that you can use in your AMP pages. {% endcall %}

Custom Styles

Sometimes you want to provide your own style. You can simply override the provided styles like the following:

amp-social-share[type="twitter"] {
  background: red;
  background-image: url(datauri:svg/myownsvgicon);
}

Variable Substitution

You can use global AMP variables substitution in the <amp-social-share> element. In the example below, TITLE is substituted with the page title and CANONICAL_URL with the document's canonical URL.

<amp-social-share type="whatsapp"
    data-param-text="Check out this article: TITLE - CANONICAL_URL">
</amp-social-share>

Validation

See amp-social-share rules in the AMP validator specification.