Sharing interactive posts

Interactive posts provide an easy and prominent way to allow users to share your site or app with their connections and invite them to take action, for example, RSVP for an event. Interactive posts can drive new users to your site, improve conversions, and increase engagement.

An interactive post in the Google+ stream is similar to a basic shared post
but adds a call-to-action button and support for deep linking.

Deep linking allows the Google+ app on mobile devices to direct clicks on an
interactive post to your mobile app if the user has it installed. If the user
does not have your app installed, they are prompted to install it.

A user sending an interactive post from a desktop web browser must sign in
to the app with Google+ and grant the app the plus.login scope.
However, a user sending an interactive post from a mobile web browser
is not required to sign in to the app or grant any permissions.
The mobile web sharebox requires your client ID to support prefilled text.

This document covers adding the sharing button for interactive posts to your
website. If you also have a mobile app, you should also implement interactive
sharing with deep linking for Android
and iOS.

More on interactive posts ››Interactive Posts

A typical scenario is as follows. Let's say you created a music-playing
app called MySongApp that supports web, Android and iOS. You implemented the
Google+ Share button on each of the song-playing pages.

Jojie is using MySongApp on any of the three platforms and is playing a song
"Love" she particularly likes. She wants to share this song with her friends,
so she taps the Share button.

This opens the Share dialog, with a preview of the song based on the content
in your app. Jojie types "I love this song", then sends it to her circles.

Three people who receive and read Jojie's post in their Google+ streams
want to listen to Jojie's song:

One person with an Android phone does not have MySongApp installed, so when she
taps the Listen link in the post, the Google Play store launches to the
MySongApp installation page. She installs MySongApp, which then launches and
deep-links directly to the song "Love" and starts playing it.

Another person with an iPhone also does not have MySongApp installed, so when she
taps the Listen link in the post, the Apple App Store launches to the
MySongApp installation page. Just like the previous example, she installs
MySongApp, which then launches and deep-links to the song and starts playing it.

A third person is using a desktop web browser, so when he clicks the Listen
link in the post, he is taken to the web page on your website that also starts
playing the song "Love".

With deep-linking, users are taken to the page in your app that gives them the best
in-app experience for their device, and are prompted along the way to install your app
only when necessary.

Desktop web

The following screenshot is of a desktop web share dialog box for an interactive post.

Mobile web

The following screenshot shows the two-screen sequence for sharing an
interactive post on mobile web.

If you plan to use deep linking into your mobile apps, create a client ID
for each of the platforms that you plan to support within the same project.
The Google+ app automatically routes a click on a deep link to the app for
the correct platform using this information.

Add the markup for the button by adding a <div>, <span>, or <button>
element to your page with a unique ID and a label for the button within the
element. Set your client ID with the value that you created in the previous
step.

Rendering the button with JavaScript

You can create an interactive post button on your page by using the JavaScript
API. You use the gapi.interactivepost.render()
method to transform an element to be an
interactive post button. For example, the following code creates a
interactive post from the element with the ID of sharePost:

The button is now enabled as an interactive post. Next, you might choose to
design the button to fit your app's design.

Interactive share button attributes

The following attributes are specified on the HTML tag that you define as your
container for the interactive post button by specifying the
class="g-interactivepost" attribute. If you are using the
JavaScript API to
render your button, remove the data- prefix from the
parameter names when calling gapi.interactivepost.render().

Key

Value

Default

Required

Description

class

string

g-interactivepost

Required

Required for rendering the button in HTML. Omit if using
gapi.interactivepost.render().

The content URL points to the page that you want to render in the
preview snippet in the share post. This URL can differ from the
call-to-action button's URL, for example, you might link to an
overview with the content URL and to a form with the call-to-action
button.

If you specify the contentdeeplinkid attribute and the
link is clicked on a mobile device, the Google+ app launches your app
and passes the contentdeeplinkid for your app to use to
determine the location within your app to take the user.

The protocol (http/https), host name, and port (if specified) for the
content URL and the
call-to-action URL must
match. Because these must match, you should avoid using URL shorteners
and redirects for either URL.

data-contentdeeplinkid

string

—

—

Specify a URI path as a deep link ID for the content link in the
shared post. The value must be 512 characters or fewer in length.

To take advantage of deep linking, your mobile app should be
configured to handle incoming deep links. For more information, see
handling incoming deep links for Android or iOS.

data-cookiepolicy

uri

single_host_origin

none

—

Required

Directs the interactive share button to store user and session
information in a session cookie and HTML5 session storage on the
user's client for the purpose of minimizing HTTP traffic and
distinguishing between multiple Google accounts a user might be signed
into. We call these two means of storage the client storage.

When a page containing a interactive share button is loaded, the
user's sign-in state can quickly be accessed from this client storage
rather than from Google servers, reducing the latency for button
loading. In addition, the cookie can allow a user who is signed in to
multiple Google accounts (say, work and personal) to select which
account to use with your website. The cookie and session storage are
deleted once the user ends their browsing session.

The value of the data-cookiepolicy attribute
determines the scope of URIs that can access the cookie. Choose this
value based on the website's domain name to set the cookie's scope.
Then the cookie can be accessed by all interactive share buttons
within that scope. You should use a policy that is as broad as
necessary for your site because that reduces the number of cookies
that your site writes to the user's client. There should ideally be
only one cookie for each distinct domain suffix you are allowed to
write cookies for (for example, one cookie each for example.com and
example.co.uk).

Available values -
Three values of data-cookiepolicy are allowed: a
uri, single_host_origin, and
none. The most versatile setting you can pass is the
uri value that most broadly matches the structure of your
website.

The uri includes the scheme,
site-domain and possibly port to be set for
your site. The value you provide determines the scope of the
cookie. The more general the uri, the broader the scope
of the cookie. The first five use
cases are examples. Specify uri in one of the
following three URI formats:

http://site_domain -
An http scheme in uri provides the broadest
scope—it sets a cookie whose scope includes both http and
https domains and all of the site's subdomains. A more specific
URI, such as http://mail.example.com, would set a
more narrowly scoped cookie that further restricts its scope to
only that domain and its subdomains.

https://site_domain -
An https scheme in uri is similar to but narrower
than http—use it for SSL-only sites. This ensures that the
cookies will have the "secure" attribute set and hence will not
be sent over an un-encrypted connection.

scheme://site_domain:port -
Using a value that includes a port number.
This value restricts the cookie's scope to only that one URI.

Note: Sites with distinct domain suffixes
(such as http://example.com and http://example.co.uk)
must have different site_domain values, and
therefore must be specified with different
data-cookiepolicy markup.

single_host_origin

Use this value if your website has only a single host name and no
subdomains (for example, host http://example.com but not
http://www.example.com). This string is shorthand for the scheme
and host name (and port number if it's not the default for the
scheme) of the current page, which then is equivalent to the
uri value above.

none

The none value does not set cookies or session
storage for the interactive share button and uses a less efficient
fallback mechanism for determining user and session information.
Setting this value to none also prevents gapi.auth.signout from
working for the user and requires you to implement signout
appropriately. This value also can prevent a user who is signed in to
multiple Google accounts (say, work and personal) from being able to
select which account to use with your website.

Note: You can identify client storage entries written
by the interactive share button by checking their prefixes:
GCSC prefix is used for session cookies and HTML5
session storage, and
G_AUTHUSER_ prefix is used for session cookies only.

The label that renders in the stream post that prompts the reader
to act. This field should be a verb that accurately describe the
action that will be taken.

The calltoactionurl must also be specified to render the
call-to-action button.

The call-to-action label is automatically translated in the Google+
stream to the viewer's language.

data-calltoactionurl

url

—

Required

The URL that the user will be taken to when the call-to-action button
is clicked from a web browser. If the button is clicked on a mobile
device, the Google+ app launches your app and passes the
calltoactiondeeplinkid for your app to use to determine
the location within your app to take the user.

The protocol (http/https), host name, and port (if specified) for the
call-to-action URL and the data-contenturl must
match. Because these must match, you should avoid using URL shorteners
and redirects for either URL.

Important: Your app or site must
validate all input and be careful about performing actions when a deep
link is clicked.

data-calltoactiondeeplinkid

string

—

—

Specify a URI path as a deep link ID for the call to action button.
The value must be 512 characters or fewer in length.

To take advantage of deep linking, your mobile app should be
configured to handle incoming deep links. For more information, see
handling incoming deep links for Android or iOS.

data-prefilltext

string

—

—

Text that is prefilled in the comment area of the share box on behalf
of the user. The user can edit or remove the prefilled text.

The maximum length of the prefilled text is 1042 characters.

data-recipients

string

—

—

A comma-separated list of user IDs and email addresses that you want
to prefill the share settings with. You can get these IDs by calling
the people.list method on
behalf of an authenticated user. A
maximum of ten recipients are allowed.

Inherited attributes from sign in

NOTE: These attributes apply only to web, not to mobile web.

data-accesstype

online

offline

online

—

If using the server-side sign-in flow and you want to get a refresh
token that you can use to make offline requests, specify this attribute
and set the value to offline.

data-approvalprompt

auto

force

auto

—

Allows control over when the user is re-prompted for consent.
When set to auto, the user only sees the OAuth consent
dialog if they have not authorized your application. When set to
force, the user is shown the OAuth consent dialog each
time that they click the sign-in button.

data-callback

function(authResult)

—

—

A function, in the global namespace, which is called after a
successful sign-in occurs. This function must hide the sign-in button.

This function is passed a single parameter: a JSON object with the
following structure:

{
"id_token": A JSON web token (JWT) that contains identity information about the user that is digitally signed by Google,
"access_token": the access token,
"expires_in": the validity of the tokens, in seconds,
"code" : a one-time code that can be sent to your server and exchanged for an access token,
"error": The OAuth2 error type if problems occurred,
"error_description": an error message if problems occurred
}

If your app will write moments, list the full URI of the types of moments that you intend to
write. For example:
http://schema.org/AddAction.

data-scope

A space-delimited list of scope URIs

https://www.googleapis.com/auth/plus.login

—

The OAuth 2.0 scopes for the APIs that you would like to use as a
space-delimited list. You can list Google+ scopes and other Google OAuth
2.0 scopes that your application might require. Find more scopes in
the OAuth 2.0
Playground.

Determining a value for cookie policy

The button attribute data-cookiepolicy
is required for the sign-in and interactive share buttons. You can specify a
value for this attribute based on the use case that best fits your needs.
These examples are in the order of broadest to narrowest scope:

A website with multiple subdomains, and possibly both https and http (such as
http://example.com, http://www.example.com, and https://secure.example.com)
should use:data-cookiepolicy="http://example.com".

A website with multiple subdomains and SSL only (https://example.com,
https://www.example.com, and https://static.example.com) should use:data-cookiepolicy="https://example.com".

A site that is part of a larger website and wants to restrict the scope to only
its subdomain (https://mydept.example.com but not
https://otherdept.example.com) should use:data-cookiepolicy="https://mydept.example.com".

A website with only one host name that runs on a non-default port
(http://dev.example.com:8080)
should use:data-cookiepolicy="http://dev.example.com:8080".

A website that has only a single host name (such as http://example.com
but not also http://www.example.com) should use:data-cookiepolicy="single_host_origin"

A website where cookies and HTML5 storage are not allowed should
use the following, but the site will suffer from degraded performance
and a user who is signed in to multiple Google accounts might not be able
to select which account to use with your website:data-cookiepolicy="none"

Script tag parameters

These parameters are defined within the <script /> element.
The parameters control the
language and
button loading mechanism that are used across the entire web page.

When you use the explicit load in conjunction with
go and render calls that point to
specific containers in your page, you prevent the script from
traversing the entire DOM, which can improve button rendering
time. See the gapi.interactivepost.go and
gapi.interactivepost.render examples.

JavaScript API

The interactive post JavaScript defines two button-rendering functions under
the gapi.interactivepost namespace. You must call one of these
functions if you disable automatic rendering by setting
parsetags to
"explicit".

Method

Description

gapi.interactivepost.render(container,parameters)

Renders the specified container as a interactive post.

container

The container to render as the interactive post. Specify either the
ID of the container (string) or the DOM element itself.

Renders all interactive post tags and classes in the specified
container. This function should be used only if parsetags
is set to explicit, which you might do for performance
reasons.

opt_container

The container containing the interactive post tags to render.
Specify either the ID of the container (string) or the DOM element
itself. If the opt_container parameter is omitted, all
interactive post tags on the page are rendered.

Button design

You have broad control over the appearance of the interactive posts button
within your app to fit with your design. The style of this button is up to you;
however, you must still follow the button policies
and branding guidelines.

The following is a basic example of creating a CSS style to apply to your
button:

You must use a DIV, SPAN, or BUTTON element for your interactive post
container element; however, you can use your own custom markup within the
container element to achieve a design that meets your needs. For example, if you
wanted to use an icon:

The markup and CSS above would create the interactive post button shown below:

Invite your friends!

You can download images, fonts, and PhotoShop source files to help with your
button design from the branding guidelines.

Troubleshooting

Shared an
interactive post, but it is not appearing in my stream

The URLs that you use for data-contenturl and data-calltoactionurl
parameters must match: protocols (http or https), domains, and port number
(if applicable). You should not use URL shorteners or redirects for either
of these URLs.

FAQs

What data is sent to Google when you click the
interactive post button?

When a user signs into your app with Google, Google will receive
information including information about the user's Google profile, the
user's IP address, and other browser or client related information. Google
may also receive details of the user's activities in your app if the app
uses the moments API methods.