Our gifting feature integrates with your system to enable subscribers to share specific pieces of otherwise-protected content to non-subscribers. This is a feature where we provide most of the infrastructure (and all of the UI) for this on our side, however we will need an API from you, details of which are below. 

The flow

Users of your app will see a CTA to gift the article inline within the page. 

When users tap on this they will see a modal allowing them to access the special GiftLink:
 

The fonts and colours on the article CTA & modal are themeable. 

Only signed-in subscribers see the CTA. The app must report an `active` authorisation state with a user token, and the article must carry a canonical URL — otherwise nothing is rendered.

How it works

We provide the out-of-the-box interface above that allows users to gift articles to other users. You can control how many gifts an user is allowed to use during a given period. 

The GiftLink endpoint is part of the entitlement implementation. We call it twice, with two different HTTP methods, at two different points in the reader's journey:

This split exists so that opening the modal — or opening it and changing their mind — never costs a reader a gift. Only an actual copy or share does. So your endpoint needs to distinguish the two: **the `GET` reports how many gifts the reader has left and mints nothing, the `POST` mints the link.**

If your system cannot report an allowance without also creating a link, tell us during integration. We can then ignore the method and treat the `GET` as a create, so the reader spends a gift on opening the modal.

We will need an API provided to us to implement this feature. This gives you full control of gifting logic and limits.

Inputs

Both calls take the same two query parameters:

- token — the user token (or PKCE access token) we receive when the user logs in
- url — the canonical URL of the article to be shared

Response

Omit any field you have no value for rather than sending it as `null`.

A call with either parameter missing returns a message-only JSON response (`Invalid or missing token parameter given` / `Invalid or missing url parameter given`).

Example responses

Allowance, answering the `GET` when the modal opens:

{
  "message": "You have 3 gift articles left to share this month.",
  "gift_shares": 3,
  "gift_limit": "4"
}

`message` can be used to carry the remaining count - it will be re-rendered after the `POST` response, so a message like *"You have 3 gift articles left to share this month."* counts down in place as the reader shares.

Created link, answering the `POST` when the reader copies or shares:

{
 "message": "Thanks for sharing!",
 "gift_code": "x1x2x3x4x5x6x7x8x9x0x",
 "gift_url": "https://pugpig.com/news/launches/?gift=x1x2x3x4x5x6x7x8x9x0x",
 "gift_shares": 2,
 "gift_limit": "10"
}

Out of gifts. Either method can return this:

{
 "message": "You've run out of shares, come back next month!",
 "gift_shares": 10,
 "gift_limit": "10"
}

We also treat an allowance response as out-of-gifts when `gift_limit` is above zero and `gift_shares` is not.

Not charging twice for the same article

We hold the response for an article for as long as the reader stays on the page, so reopening the modal, or copying and then sharing, does not send a second `POST`.

That is not persisted, though — if the reader reloads the article and shares again, you will get a fresh `POST` for an article they have already gifted. Your endpoint needs to recognise that and not spend a second gift.

Redemption

Most users that redeem the gift will end up on your website - we are assuming that the your website will implement the gift token checking on your side.

We recommend using the App Association File/Google file patterns to prevent Gift URLs opening in the app (for example, prevent all URLs with www.yoursite.com?gifttoken=123456)

 

Piano

Piano does not provide an API for gifting articles, which means we cannot implement the flow as described above in your app. However, as part of Composer Piano does have a ‘Share with a Friend' feature which serves essentially the same purpose. This is a web experience but if you have it set up for your website, the same experience can be embedded inline within your app articles. As with API-driven gifting the redemption of gifted articles happens on your website, not in the app.

Get in touch with support if you'd like to set this up. Please ensure you've first read the ‘Considerations’ section in the Piano doc linked above if you aren't already familiar with the feature from using it on your site (you'll see it does work slightly differently from the API method explained above). You will need to already have the Composer experience set up in order for our support team to implement it in your app.

Example of the out-of-the-box Piano-provided UI: