Publishers
RAMP Quiz
Self-Service or Managed Service?

Find out which approach is right for you!

Take the Quiz

Advertisers
the-flex-suite
Flex Suite

Learn more about Playwire's Flex Suite!

Learn More

About
Managed-Service Graphic
Get in Touch

Reach out to the Playwire team.

Contact Us

Learn
Close
Learning Center

Google Subscription Linking Implementation Guide: swg.js, PPIDs, and the Revenue Case for Building It Right

May 20, 2026

Show Editorial Policy

shield-icon-2

Editorial Policy

All of our content is generated by subject matter experts with years of ad tech experience and structured by writers and educators for ease of use and digestibility. Learn more about our rigorous interview, content production and review process here.

Publisher Provided Identifiers Google Reader Revenue Manager Subscription Linking swg.js Implementation First-Party Identity
Google Subscription Linking Implementation Guide: swg.js, PPIDs, and the Revenue Case for Building It Right
Ready to be powered by Playwire?

Maximize your ad revenue today!

Apply Now

Key Points

  • Subscription Linking requires five distinct technical components working together: a Google Cloud project, an OAuth service account, structured data on every article page, swg.js client integration, and a server-side entitlement sync API.
  • The PPID you generate for Subscription Linking is the same identifier that flows into Google Ad Manager 360 for programmatic targeting on cookie-less inventory. Getting it right upstream pays dividends downstream.
  • Google beta partners running PPIDs on inventory without other identifiers reported a 15%+ lift in programmatic auction revenue, making this identity infrastructure directly connected to your ad revenue, not separate from it.
  • Entitlement records go stale and get deleted by Google; your server-side sync must run on a regular schedule or your linked subscribers lose their personalized surfaces.
  • This integration is not a weekend project: budget 4-6 weeks of engineering time for a production-quality implementation.

Most publishers reading about Subscription Linking focus on the engagement upside: the "From your subscriptions" carousels in Google Search and Discover, the 34% pageview lift The Indian Express measured among linked subscribers vs. 9% for unlinked. That's all real.

What gets less attention is the implementation surface area. Subscription Linking isn't a snippet you drop in a <head> tag. It's five distinct technical components that have to work together, and if any one of them is misconfigured, the whole thing silently breaks. This guide covers all five in the order you'll actually build them, plus the revenue case for doing so.

The Revenue Case Before You Write a Single Line of Code

Before touching any infrastructure, understand what you're actually building toward. This is not a Google-hosted personalization feature you're deploying for engagement metrics. It's first-party identity infrastructure that directly affects programmatic revenue.

Safari carries roughly 31% of US browser traffic, and Firefox adds another ~4%. Both block third-party cookies by default. Privacy-conscious Chrome users opt out at meaningful rates on top of that. Google's own Privacy Sandbox testing showed a 34% drop in programmatic revenue for Google Ad Manager publishers operating without third-party cookies and no replacement identifier.

PPIDs are that replacement. Google documented that beta partners running PPIDs on inventory without other identifiers saw a 15%+ lift in programmatic auction revenue. INMA's predictive modeling puts the net revenue gain from converting an anonymous reader to a known reader at 3.4X. For a deeper look at how that conversion math works in practice, see our guide on how identified readers translate to higher ad revenue.

The PPID you generate through Subscription Linking is the same identifier that flows into your GAM 360 demand channel settings. The identity infrastructure you're building here is upstream of your ad revenue, not a separate subscriber engagement project. Our guide on publisher provided identifiers and how PPIDs recover cookie-less ad revenue covers the auction mechanics in full if you want the complete picture before you start building.

One thing to be clear about upfront: Subscription Linking does not improve your organic search rankings. It surfaces your content in a personalized "From your subscriptions" module in Google Search and Discover, but only for users who have already linked their account. It reaches your existing converted audience more effectively. It doesn't help you rank higher for new readers who've never heard of you. That distinction matters when you're setting stakeholder expectations. If you've seen claims to the contrary, our piece on whether Google Subscription Linking improves SEO addresses them directly.

Prerequisites: What You Need Before You Start

Missing a prerequisite is the fastest way to produce 403 errors you can't diagnose. Confirm all of these are in place before writing any implementation code.

  • RRM Enterprise (RRME) enabled: Subscription Linking requires RRM Enterprise, not RRM Standard. Standard is the UI-driven, no-code variant. Enterprise is the API-driven path. If you're not sure which you're on, check your Publisher Center settings: Standard has no API access, Enterprise does. The migration path is documented here. For a breakdown of when to upgrade and what you gain, see our RRM Standard vs. Enterprise comparison.
  • Publisher Center publication configured: Your publication must be set up and verified in Publisher Center before you can link a Cloud project to it.
  • Domain verified in Google Search Console: The domains serving your publication content must be verified in Search Console. This is required for structured data validation and Subscribed Content report access.
  • Google Ad Manager 360 access: If you want the PPID programmatic lift, you need GAM 360. PPID for programmatic is not available on GAM Small Business networks. This is a hard constraint.
  • Subscriber identity infrastructure: You need an existing user database with stable user IDs to derive PPIDs from. If readers don't have persistent accounts on your platform, PPID generation becomes significantly more complex.

Non-news publishers should note: Subscription Linking is available to all publishers with paying readers, not just news. Gaming, sports, education, and entertainment publishers who run subscription or membership models qualify. Most outside the news vertical don't realize this tool applies to them.

What You're Building: The Full Integration Flow

A complete Subscription Linking integration moves through five components in sequence. The flow: a reader on your site clicks to link their subscription, swg.js fires a linkSubscription call that associates their Google Account with a Publisher Provided Identifier (PPID), and your server pushes entitlement data to Google's API so the personalization surfaces know which content that reader can access.

The five components, in build order:

  • Google Cloud Project: the authentication and API infrastructure backbone
  • OAuth service account: credentials for server-to-server API calls
  • Structured data on article pages: tells Google which content is gated and what the publication ID is
  • swg.js client integration: handles the reader-facing linking flow
  • Server-side entitlement sync: keeps Google's records fresh and prevents staleness deletion

Build in this order. Skipping ahead, particularly adding swg.js before the Cloud project is configured, produces 403 errors that are painful to debug.

Essential Background Reading:

Component 1: Google Cloud Project Setup

The Google Cloud project is the authentication layer for everything else. You need one Cloud project with the Subscription Linking API enabled, linked to your Publisher Center publication, with authorized JavaScript origins configured for client-side calls.

Start at console.cloud.google.com. Create a new project or use an existing one that has no conflicting API configurations. Then:

  • Go to APIs & Services > Library and search for "Subscription Linking API"
  • Enable it for your project
  • Go to APIs & Services > Credentials and create a service account (covered in Component 2)
  • In Publisher Center, navigate to your publication settings and link the Google Cloud project by entering the project ID

The project-to-publication link is the step that gets skipped most often, and it's the single most common root cause of 403 errors on later API calls. Google's API cannot authorize your service account until it can trace the service account back to a publication you own.

One project serves one publication. Portfolio publishers running multiple sites need multiple Cloud projects: plan that overhead into your scoping before you start.

Component 2: OAuth Service Account Configuration

The Subscription Linking API uses OAuth 2.0 service account authentication, not API keys. Service accounts authenticate server-to-server, which is correct here. You never want reader entitlement sync going through a client-side credential.

In the Cloud project you just created:

  • Go to IAM & Admin > Service Accounts > Create Service Account
  • Give it a descriptive name (e.g., subscription-linking-sync)
  • On the Keys tab, create a new key in JSON format and download it
  • Store the JSON key file in environment variables or a secrets manager, never in your repo

The service account needs the readerrevenue.subscriptionlinking.manage OAuth scope. This isn't a Cloud IAM role you assign in the console; it's a scope you request in your server-side OAuth flow when generating access tokens.

Your token generation code will look something like this, using the Google Auth Library:

javascript 
from google.oauth2 import service_account

SCOPES = ['https://www.googleapis.com/auth/readerrevenue.subscriptionlinking.manage']

credentials = service_account.Credentials.from_service_account_file(
    'path/to/service-account-key.json',
    scopes=SCOPES
)

# Use credentials.token after calling credentials.refresh(Request())
 

Generate a fresh access token before each API call or implement token caching with expiry tracking. Service account tokens expire after one hour. Stale tokens produce 401 errors; a misconfigured service account produces 403s. These are different problems, but both look like auth failures at first glance.

Related Content:

Component 3: Structured Data on Article Pages

Every article page needs two layers of structured data: a publication identifier for Subscription Linking, and, if the content is gated, the isAccessibleForFree + hasPart pattern to keep Google's indexing accurate.

Publication Identifier Markup

Google's Subscription Linking requires structured data on every article page that includes your publication ID. This is how swg.js knows which publication to associate the linking action with. The markup goes in a JSON-LD script block:

json 
{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "isPartOf": {
    "@type": ["CreativeWork", "Product"],
    "name": "Your Publication Name",
    "productID": "your_publication_id:showcase"
  }
}

Your publication ID is the ID from your Publisher Center publication configuration, not your Publisher Center account ID. It's the ID at the publication level, one level deeper.

Gated Content Markup

If the page is behind a registration wall or paywall, add the isAccessibleForFree signal:

json 
{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "isAccessibleForFree": false,
  "hasPart": {
    "@type": "WebPageElement",
    "isAccessibleForFree": false,
    "cssSelector": ".paywall"
  },
  "isPartOf": {
    "@type": ["CreativeWork", "Product"],
    "name": "Your Publication Name",
    "productID": "your_publication_id:showcase"
  }
}

The CSS selector in hasPart must match the element you're actually hiding from non-subscribers. If it doesn't match, or if you're conditionally rendering the element server-side and Googlebot sees different content than your users, you're in cloaking territory. That's how The Wall Street Journal saw a 44% search traffic drop after removing Google's First Click Free access without proper markup in place.

For the complete specification on this markup pattern, including how to handle metered content and mixed-access pages, our isAccessibleForFree implementation guide for paywalled and gated content has the full treatment. The Google paywalled content structured data guidelines covers the canonical Google Search Central requirements alongside it.

Run every templated article page type through the Rich Results Test after deployment. Then check the Subscribed content report in Google Search Console regularly: it surfaces indexing errors specific to this markup pattern.

Structured Data Requirements by Page Type

Page typePublication ID markupisAccessibleForFree markupNotes
Free articleRequiredNot requiredAdd anyway for consistency
Metered article (within limit)RequiredRequired (true)Googlebot sees full content
Paywalled articleRequiredRequired (false)cssSelector must match hidden element
Registration-gated articleRequiredRequired (false)Same as paywall pattern
Non-article pagesNot requiredNot requiredHomepage, section pages exempt

Component 4: swg.js Client Integration

swg.js is the Subscribe with Google client library. It handles the reader-facing flow: detecting entitlements, displaying CTAs, and executing the linking action. It needs to be present on every page where a paywall or registration wall might appear.

Loading swg.js

Add this script tag to your page <head>:

javascript 
<script async
  subscriptions-control="manual"
  type="application/javascript"
  src="https://news.google.com/swg/js/v1/swg.js">
</script>

The subscriptions-control="manual" attribute matters. Without it, swg.js will attempt automatic entitlement checks and CTA rendering before your custom logic can run. Manual mode gives you control over when and how the library initializes.

Initializing the Client

javascript 
(self.SWG = self.SWG || []).push(async (subscriptions) => {
  subscriptions.configure({
    paySwgVersion: '2'
  });
  
  await subscriptions.init('your_publication_id');
  
  // Your custom entitlement and linking logic goes here
});

Calling linkSubscription

The linkSubscription method is the core of the Subscription Linking flow. When a subscriber clicks your "Link to Google" CTA, you call:

javascript 
await subscriptions.linkSubscription({
  publisherProvidedId: 'ppid_for_this_user'
});
 

The publisherProvidedId value is the PPID you've generated for this reader (covered in the next component). The method opens a Google-hosted overlay that walks the reader through granting permission and connecting their Google Account. After completion, swg.js returns a result object you can use to confirm the linking succeeded.

A few implementation notes worth flagging:

  • The PPID you pass here cannot be updated later without the reader unlinking and re-linking. Get it right before calling linkSubscription. If you're hashing a user ID, make sure your hashing function is stable.
  • Call getEntitlements() before showing the link CTA to confirm the reader is a subscriber. Showing a "Link your subscription" button to a non-subscriber creates a confusing UX that will generate support tickets.
  • Handle the flow asynchronously. The linking overlay is a modal requiring user interaction. Don't block your page render waiting for it.

Checking Entitlements Before the Link CTA

javascript 
const entitlements = await subscriptions.getEntitlements();

if (entitlements.enablesThis()) {
  // Reader has a valid entitlement for this content
  // Check if they've already linked
  const account = entitlements.getEntitlementForSource('google');
  
  if (!account) {
    // Show the "Link to Google" CTA
    showLinkSubscriptionButton();
  }
}
 

Component 5: PPID Generation Strategy

The PPID is the persistent identifier that ties a reader's subscription to their Google Account. It flows into Subscription Linking, into GAM 360 for programmatic targeting, and into any audience segments you build in Audience Solutions. Its properties matter significantly.

What Makes a Good PPID

PPIDs must be:

  • Stable: The same reader must always get the same PPID. If your generation logic changes, existing links break and affected readers have to re-link.
  • Opaque: No raw PII. Names, email addresses, and phone numbers should never appear in a PPID.
  • Unique per user: One reader, one PPID, across all their devices and sessions.
  • Consistent across your properties: If you're running Subscription Linking on multiple publications, decide whether you want cross-property PPIDs or per-publication PPIDs. Cross-property PPIDs simplify entitlement management but require more careful audience data governance.

The Standard Approach

Hash the user's internal database ID using a one-way hash function. SHA-256 is the standard choice:

javascript 
import hashlib

def generate_ppid(user_id: str, salt: str) -> str:
    value = f"{salt}:{user_id}"
    return hashlib.sha256(value.encode()).hexdigest()

The salt is a secret stored in your environment configuration. It prevents someone from reverse-engineering your user IDs from a leaked PPID. Store it with the same security posture as your database credentials.

Don't use email addresses as PPIDs, even hashed. Email addresses change. Users abandon accounts. The 1:1 mapping between a user's database record and their PPID should be stable for the lifetime of that account.

The PPID-to-GAM 360 Bridge

This is the connection most Subscription Linking implementations miss entirely, and it's where the programmatic revenue lift actually materializes.

Once you're generating stable PPIDs through Subscription Linking, you need to activate them in GAM 360. Navigate to Delivery > Demand channel settings > Publisher data sharing > Publisher provided identifiers (PPID) for programmatic and toggle PPID on per demand channel. Google demand, Authorized Buyers, and Open Bidders each have separate toggles.

When a bid request goes out on Safari, Firefox, or opted-out Chrome inventory, the PPID travels with it. Buyers who would otherwise see an unidentified impression can now apply audience targeting and frequency capping. That's the mechanism behind the 15%+ programmatic auction revenue lift. Without the GAM 360 activation step, the PPID exists in your Subscription Linking flow but produces no programmatic benefit.

One privacy note worth understanding: before GAM shares PPIDs with Google demand partners, it converts them into per-publisher partitioned IDs. Your users cannot be identified across other publishers' sites. The privacy protection is built in without sacrificing targeting capability on your own inventory.

Next Steps:

Component 6: Server-Side Entitlement Sync

This is the component most implementations get wrong. Google's record of a PPID's entitlements goes stale and gets deleted if it isn't kept fresh. When that happens, the reader's "From your subscriptions" surface goes dark and they lose the personalization they opted into, with no visible error message to tell you it happened.

The API Endpoints

The Subscription Linking API base URL is:

bash 
https://readerrevenuesubscriptionlinking.googleapis.com/v1/publications/{publicationId}/readers/{ppid}/entitlements

The three operations you need to implement:

MethodOperationWhen to call
PATCHCreate or update entitlementsOn subscription creation, renewal, or change
GETVerify current entitlement stateDiagnostic use; confirm sync worked
DELETERemove entitlementsOn cancellation or user data deletion request

The PATCH Request

javascript 
import requests

def sync_entitlements(ppid: str, publication_id: str, access_token: str):
    url = (
        f"https://readerrevenuesubscriptionlinking.googleapis.com/v1/"
        f"publications/{publication_id}/readers/{ppid}/entitlements"
    )
    
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "entitlements": [
            {
                "subscriptionToken": "your_internal_subscription_reference",
                "source": "YOUR_PUBLICATION_ID",
                "products": ["your_publication_id:showcase"]
            }
        ]
    }
    
    response = requests.patch(url, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

The subscriptionToken is an opaque string you define, your internal reference for this subscription. Google stores it and returns it in getEntitlements() responses so your client-side code can verify the entitlement against your own records.

The 30-Day Staleness Rule

Google deletes entitlement records that haven't been updated within approximately 30 days. A subscriber who doesn't visit your site for a month loses their linked personalization unless your sync runs independently of user activity.

Build a scheduled job that runs PATCH updates for all active subscribers on a regular cadence. Weekly is safe. Monthly is risky. Daily is fine if your infrastructure handles it without database load issues.

Your sync job should also handle:

  • Subscription renewals: PATCH with updated subscriptionToken if your renewal creates a new record
  • Plan changes: PATCH with updated product entitlements
  • Cancellations: DELETE the entitlement record immediately on cancellation processing
  • User data deletion requests: Send via the IAB Data Deletion Request Framework endpoint: https://securepubads.g.doubleclick.net/user_data_deletion?ppid={user_ppid}&iu={gam_network_code}

The deletion obligations have three distinct layers: user-initiated unlinking from their Google Account, user-requested PPID deletion from your publisher systems, and stale entitlement decay. All three require operational processes that run on an ongoing basis.

Troubleshooting Common Errors

Most implementation failures fall into four categories.

ErrorLikely causeFix
403 Forbidden on API callsService account not linked to publication via Cloud projectVerify Cloud project ID is entered in Publisher Center publication settings
403 Forbidden on API callsWrong OAuth scopeConfirm readerrevenue.subscriptionlinking.manage scope in token request
401 Unauthorized on API callsExpired access tokenImplement token refresh; tokens expire after 1 hour
swg.js overlay doesn't appearPublication ID mismatch between structured data and init() callConfirm productID in JSON-LD matches the ID passed to subscriptions.init()
getEntitlements() returns emptyEntitlement sync hasn't run or record is staleTrigger a manual PATCH call for the affected PPID and verify with GET
Linking completes but Discover/Search surface doesn't updateGoogle indexing delayNormal; allow 24. 72 hours after first linking for surfaces to populate
CTA won't loadAuthorized JavaScript origins not configured in GCPAdd your production and staging domains to the authorized origins list in Cloud project credentials

The 403 errors deserve extra attention because they're the most common and the most confusing. A 403 on the Subscription Linking API almost never means your credentials are wrong in the traditional sense: it means the authorization chain is broken somewhere between your service account, your Cloud project, and your Publisher Center publication. Work through that chain systematically before touching your credentials.

If the "From your subscriptions" surface isn't appearing for newly-linked users, check the Subscribed Content report in Search Console first. Indexing delays and structured data validation errors are the two most common culprits, and the report surfaces both.

See It In Action:

  • Squaredle Case Study: How a technically complex single-page app doubled ad revenue with a partner who could match their implementation depth.
  • Kids Education Website Case Study: Ad monetization strategy for an education publisher navigating privacy compliance and audience quality requirements.
  • Brickset Case Study: How a specialist community publisher unlocked premium CPMs through audience segmentation and direct sales activation.
  • Ad Monetization Case Studies: The full library of publisher outcomes across gaming, education, entertainment, and news verticals.

Engineering Scope Estimate

Be honest with your stakeholders about what this takes. A production-quality Subscription Linking implementation from zero to monitored-and-live looks like this:

PhaseTasksEstimated engineering time
InfrastructureCloud project, service account, Publisher Center link1. 2 days
Structured dataAudit all article templates, deploy JSON-LD patterns, validate in Search Console3. 5 days
swg.js integrationLoad library, implement init, entitlement check, link CTA3. 5 days
PPID systemGenerate stable PPIDs, store mappings, document rotation policy2. 3 days
Entitlement sync APIServer-side PATCH/DELETE, scheduled refresh job, deletion handling5. 7 days
Testing and QAEnd-to-end subscriber flow, staleness simulation, error handling3. 5 days
Total 4. 6 weeks for one experienced backend engineer

That estimate assumes no pre-existing identity infrastructure to integrate with. Publishers with a mature user database and established API patterns can compress the PPID and entitlement phases. Publishers running a headless CMS with complex article templating may need more time on the structured data phase.

Portfolio publishers should also factor in the multi-publication overhead: one Cloud project per publication, separate entitlement sync jobs per publication, and a decision on whether PPIDs are shared cross-property or scoped per-publication.

Frequently Asked Questions

What is Subscription Linking?

Subscription Linking is a feature of Google Reader Revenue Manager Enterprise that connects a publisher's subscriber accounts to readers' Google identities. Once linked, Google surfaces the publisher's content in a personalized "From your subscriptions" module on Google Search results pages and in Google Discover. Publishers also receive a Publisher Provided Identifier (PPID) that can be passed into Google Ad Manager 360 for programmatic targeting on cookie-less inventory.

Does Subscription Linking improve search rankings?

No. Subscription Linking does not affect organic search rankings. It surfaces content in a personalized module for users who have already linked their subscription, a separate UI element from organic results, visible only to that specific user. New readers browsing Google Search see no benefit. The value is engagement deepening with your already-converted subscriber base, not ranking improvement for new audience acquisition.

What is a Publisher Provided Identifier (PPID)?

A PPID is a stable, opaque, publisher-generated identifier assigned to a reader and passed to Google systems. In the context of Subscription Linking, the PPID associates a reader's subscription entitlements with their Google Account. The same PPID also flows into Google Ad Manager 360, where it enables audience targeting and frequency capping on inventory where third-party cookies are unavailable, such as Safari and Firefox traffic.

What does Subscription Linking require to implement?

A complete Subscription Linking implementation requires: RRM Enterprise (not RRM Standard), a Google Cloud project with the Subscription Linking API enabled, an OAuth 2.0 service account, structured data on every article page, swg.js client library integration, a stable PPID generation system, and a server-side entitlement sync API with a scheduled refresh job. Accessing the programmatic revenue benefits additionally requires Google Ad Manager 360.

Can non-news publishers use Subscription Linking?

Yes. Subscription Linking is available to all publishers with paying readers, including gaming, sports, education, and entertainment publishers. The requirement is that readers have paid subscriptions or memberships, not that the publisher produces news content. Most publishers outside the news vertical aren't aware this tool applies to them.

What happens if entitlement records go stale?

Google deletes entitlement records that haven't been updated within approximately 30 days. When this happens, the affected reader's "From your subscriptions" surface stops showing the publisher's content, with no error message visible to the publisher or reader. The fix is a scheduled server-side PATCH job that updates all active subscriber entitlements on a weekly cadence, independent of whether those subscribers have recently visited the site.

How Playwire Fits Into This Stack

Our RAMP platform comes complete with a Hashed Email API that allows publishers to securely transmit matched emails up the supply chain to advertisers for bidding and inclusion in our Data Management Platform. Whether you use Google's tools for capturing subscriptions or any others, we have the infrastructure to turn those emails into higher CPMs.

The 15%+ programmatic lift Google documented for PPID-enabled inventory doesn't happen automatically. It happens when the identifier flows cleanly from your subscriber database through the entitlement sync API through GAM 360 into the auction, every link in that chain optimized. That's the work we do.

If you're evaluating this integration and want to understand what the revenue impact looks like for your specific traffic profile, talk to our team. We've got the data to back it up.

Ready to put first-party identity to work? Apply to work with Playwire.

New call-to-action
Publisher Provided Identifiers Google Reader Revenue Manager Subscription Linking swg.js Implementation First-Party Identity

Related Articles