Entitlements

Users prefer watching or listening to content from the service providers they have subscriptions with. If Google knows users have access (entitlement) to certain content on your app or platform, Google can construct a better search result or response to direct the users to the content they have access to.

Figure 1. Entitlements help your subscribers access the content on your app or platform.

To determine whether a user has access to your content, Google takes the following steps:

  • Makes an API call to your entitlements endpoint to receive the user's entitlements.
  • Looks up the content's required entitlements from your Media Actions feed.
  • Determines that the user has access to the content if one of the user's entitlements matches at least one of the content's entitlements.

Entitlement identifier

An entitlement identifier (entitlementId) refers to a string that represents access to a group of content in your media catalog. Google matches a user's entitlementId to content's entitlementId from your Media Actions feed to determine whether the user has access to the content—one of the user's entitlementIds must match the value of the identifier property of the content's media subscription object in the feed.

Figure 2. One of the user's entitlements matches the content's required entitlement.

While you can use any arbitrary string for entitlementId, Google recommends the following syntax:

<domain name> + colon (:) + <access level to content>

Examples: example.com:basic, example.com:premium, example.com:sports.

The following setup makes Movie XYZ available to users with entitlementId of example.com:basic:

  • MediaExampleCompany hosts movies on example.com.
  • Movie XYZ requires the basic access level from the subscribers.
  • MediaExampleCompany's feed specifies that Movie XYZ requires entitlementId of example.com:basic, as shown below:

    {
      "@context": ["http://schema.org", {"@language": "en"}],
      "@type": "Movie",
      "@id": "www.example.com/movie_xyz",
      "url": "www.example.com/movie_xyz",
      "name": "Movie XYZ",
      "potentialAction": {
        "@type": "WatchAction",
        "target": [ … ],
        "actionAccessibilityRequirement": {
          "@type": "ActionAccessSpecification",
          "category": "subscription",
          "requiresSubscription": {
            "@type": "MediaSubscription",
            "@id": "http://www.example.com/basic_subscription",
            "name": "Basic subscription",
            "identifier": "example.com:basic",
            ...
          },
          ...
        }
      },
      ...
    }
    

Entitlements use cases

The entitlements data model provides flexibility to work with different types of subscription models, such as tiers and add-ons, and different types of media content, such as live TV.

Tiers

In a tiers subscription model, a service provider has multiple subscription tiers; for instance, Gold, Silver, and Bronze. Users with the upper tier subscription have access to all the content in the lower tiers; however, users with the lower tier subscription do not have access to the content in the upper tier.

Figure 3. A tiers subscription model and its representation of entitlements.

Consider the following scenario:

  • Jane subscribes to the Gold tier.
    • Your entitlements endpoint returns the following entitlementId:
      • example.com:bronze, example.com:silver, and example.com:gold.
  • John subscribes to the Bronze tier.
    • Your entitlements endpoint returns the following entitlementId:
      • example.com:bronze.
  • Your Media Actions feed describes the following:
    • Movie A requires example.com:bronze.
    • Movie B requires example.com:silver.

In this scenario, Google determines the following access levels for the users:

  • Both Jane and John have access to Movie A.
  • Jane has access to Movie B, but John does not have access to Movie B.

Add-ons

In an addons subscription model, a service provider allows users to add channels to a base subscription. Users can expand their entitlements by adding as many channels as desired.

Figure 4. An addons subscription model and its representation of entitlements.

Consider the following scenario:

  • Jane has PRO and Sportz in addition to the Basic subscription.
    • Your entitlements endpoint returns the following entitlementId:
      • example.com:basic, example.com:pro, and example.com:sportz.
  • John only has the Basic subscription.
    • Your entitlements endpoint returns the following entitlementId:
      • example.com:basic.
  • Your Media Actions feed describes the following:
    • Movie A requires example.com:basic.
    • Movie B requires example.com:pro.

In this scenario, Google determines the following access levels for the users:

  • Both Jane and John have access to Movie A.
  • Jane has access to Movie B, but John does not have access to Movie B.

Live TV

In a Media Actions feed, you can restrict access to a TV channel (BroadcastService) in the following two ways:

  • Based on the user's device location.
    • Specify the area where users have access to the TV channel.
    • This condition usually applies to local broadcast TV channels.
  • Based on the user's account status.
    • If access to a TV channel depends on a user's account-level setting, use entitlements to represent the restriction.
    • This condition applies to the following examples:
      • Bundle - National channels are often included in bundles, and users choose which bundle they want to subscribe to (see Tiers).
      • Add-on - Some premium channels require users to selectively add extra channels to their subscription (see Add-ons).
      • Regional Sports Network (RSN) - RSNs are usually associated with a user's home location; even when users travels outside of the RSN's area, they still have access to the RSN.

Access restriction via device location

If you want to restrict access to your TV channel based on the user's current device location, you can specify the area of restriction using either one or both of the following properties:

You don’t need to provide the ineligibleRegion property if the TV channel is available everywhere within the eligibleRegion property.

These properties take either a list of Country/City/State , a GeoShape object (See the GeoShape properties section for detailed requirements), or a list of GeoShape objects.

If the TV channel is available globally, use the following special value for eligibleRegion:

"eligibleRegion": "EARTH",

Example of eligibleRegion with a list of countries:

"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/north_america_network/subscription"
  },
  "eligibleRegion": [
    {
      "@type": "Country",
      "name": "US"
    },
    {
      "@type": "Country",
      "name": "CA"
    }
  ]
}

Example of eligibleRegion with a GeoShape object that contains a list of ZIP codes:

"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription"
  },
  "eligibleRegion": {
    "@type": "GeoShape",
    "@id": "http://example.com/area1",
    "addressCountry": "US",
    "postalCode": [
      "94118",
      "94119"
    ]
  }
}

Example of eligibleRegion with a GeoShape object that contains a list of FSA (forward sortation area) codes:

"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription"
  },
  "eligibleRegion":{
    "@type": "GeoShape",
    "@id": "http://example.com/area2",
    "addressCountry": "CA",
    "postalCode": [
      "1A1",
      "K1A"
    ]
  }
}

Example of eligibleRegion with a GeoShape object that contains a DMA ID:

"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/abcd/subscription"
  },
  "eligibleRegion":{
    "@type": "GeoShape",
    "@id": "http://example.com/area3",
    "addressCountry": "US",
    "identifier": [
      {
        "@type": "PropertyValue",
        "propertyID": "DMA_ID",
        "value": "501"
      }
    ]
  }
}

Example of eligibleRegion with a list of GeoShape objects each containing a DMA ID:

"actionAccessibilityRequirement" : {
   "@type" : "ActionAccessSpecification",
   "eligibleRegion" : [
      {
         "@id" : "http://example.com/dma/601",
         "@type" : "GeoShape",
         "addressCountry" : "US",
         "identifier" : {
            "@type" : "PropertyValue",
            "propertyID" : "DMA_ID",
            "value" : "601"
         }
      },
      {
         "@id" : "http://example.com/dma/602",
         "@type" : "GeoShape",
         "addressCountry" : "US",
         "identifier" : {
            "@type" : "PropertyValue",
            "propertyID" : "DMA_ID",
            "value" : "602"
         }
      }
   ]
}

Access restriction via entitlements

If you want to restrict access to your TV channel based on the user's account status (that is, independent of device location), specify your TV channel's entitlementId in the identifier property of a media subscription object in the feed, as shown below:

"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/sports_tv/premium_subscription",
    "name": "Premium Sports TV subscription",
    "identifier": "example.com:premium"
  }
}

Entitlements endpoint

Use the information from this section to host an HTTPS endpoint that returns the entitlements associated with a user.

Prerequisite

Before you begin, verify that your service supports the OAuth 2.0 flow with Google.

Request

To receive a user's entitlements, Google sends a request that contains the user's OAuth token, as shown below. Your endpoint needs to identify the user based on this OAuth token.

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer <OAuthToken>

Response

Your endpoint needs to return a response with the following properties:

Property Description
entitlement Required. This property contains entitlementId that the user holds.
expiration The expiration date of this entitlement, in ISO 8601 format (including timezone).

Example of a user who has access to example:basic and example:premium:

{
  "entitlements": [
    {
      "entitlement": "example.com:basic"
    },
    {
      "entitlement": "example.com:premium"
    }
  ]
}

Example of a user's entitlements and expiration dates:

{
  "entitlements": [
    {
      "entitlement": "example.com:basic",
      "expiration": "2019-10-11T10:00:00Z"
    },
    {
      "entitlement": "example.com:premium",
      "expiration": "2019-05-22T07:15:29Z"
    }
  ]
}

Example of a user who has no entitlements:

{
  "entitlements": []
}

Rate limit

Google refreshes a user's entitlements information up to every 6 hours. To smooth out the max queries per second (QPS), Google distributes the queries to your endpoint evenly over time. Thus, you can estimate the expected average QPS for your endpoint using the following formula:

Expected average QPS = <total number of users> / 21600 seconds (6 hr x 60 min x 60 sec)

If you support a large number of users, Google can adjust the 6-hour interval. Contact Google to discuss the configuration if necessary.

Contact Google

When your endpoint is ready, contact Google to inform the endpoint's URL.