Google Play External Content Links reporting with FastSpring

This page shows how to report FastSpring transactions back to Google Play's External Content Links program (the Android steering program), so an Android steering integration stays compliant. It's an extension of an existing Steer Safe integration, not a standalone build. See What needs to already be in place below.

This page covers a working reference implementation from the FSBuilds GitHub repository, found in the fsbuilds-google-external-linking folder of the FastSpring fsBuilds examples repo.

Scope note: the purpose of this build is to compliantly report transactions to Google. It's a US program specifically. Two things are deliberately out of scope:

• External Content Links also covers linking to external app downloads. Although part of the same program, that's a different flow with its own enrollment and reporting steps, and isn't covered here.
• Google's separate External Offers, Alternative Payments, and Payment Choice programs. External Content Links is the program specific to the US, with its own APIs. These programs aren't interchangeable.

What needs to already be in place

This repo assumes an existing FastSpring Steer Safe integration already works. Confirm you have these three pieces in place before going further.

Because the app is already published on Play Billing, the required Google Play Developer API is largely set up. The one thing that may still need attention is permissions on the existing service account (see Enrollment and setup, step 4).

How it works

This section gives a high-level view of how the existing Steer Safe flow gains two additions: an eligibility check and token up front, and a Google report after purchase. The base flow doesn't change.

1. Initiate purchase.
2. Check eligibility.
3. Generate a single-use token.
4. Show Google's disclosure.
5. Tag the token onto the FastSpring order.
6. Checkout (unchanged Steer Safe flow).
7. Webhook grants currency and reports to Google in parallel.
8. Client confirms on return.

sequenceDiagram
    participant Player
    participant Client as Unity Client
    participant GPB as Google Play Billing
    participant Backend
    participant FS as FastSpring

    Player->>Client: Tap Buy
    Client->>GPB: Connect, check eligibility
    GPB-->>Client: Eligible
    Client->>GPB: Generate external transaction token
    Client->>GPB: launchExternalLink (shows disclosure dialog)
    Player->>GPB: Acknowledges dialog
    Client->>Backend: POST /encode (product, token)
    Backend-->>Client: Signed checkout URL (securePayload + secureKey)
    Client->>FS: Opens checkout (Custom Tab, WebView, or browser)
    Player->>FS: Completes payment
    FS-->>Player: Redirect to deep link (fastspring://shop-return)
    FS->>Backend: Webhook: order.completed (signed, HMAC)
    par Grant currency
        Backend->>Backend: UGS Economy virtual purchase
    and Report to Google
        Backend->>GPB: POST externalTransactions (real order data)
    end
    Player->>Client: App resumes via deep link
    Client->>Backend: (fallback) POST /reportTransaction
    Client->>Client: Poll balance, show thank-you popup

Currency granting and Google reporting are two independent obligations. Entitlements arrive purely through the FastSpring webhook as part of the standard Steer Safe flow, and aren't detailed further here. Google reporting is a compliance step the program requires. A reporting failure there never blocks or reverses the purchase.

Enrollment and setup

Complete these one-time account and permissions steps with Google before any of the code below will work. Verified as of September 2026.

Client implementation (Unity)

These are the four additions to your existing Unity Steer Safe client, in the order you'd make them. This is scoped to games built in Unity, via Unity IAP's ExternalBillingProgramClient (UnityEngine.Purchasing.GoogleBilling.Models). It's additive to an existing Play Billing integration; the surrounding checkout mechanics (secure payload, deep link return, balance polling) are the same Steer Safe mechanism you already have. GoogleBillingManager.cs (documentation) in this repo is the tested reference implementation.

using UnityEngine.Purchasing.GoogleBilling.Models;
using UnityEngine.Purchasing.Models;

private ExternalBillingProgramClient _billingClient;
private bool _isConnected;

void Awake()
{
    _billingClient = new ExternalBillingProgramClient();
}

void OnDestroy()
{
    _billingClient?.EndConnection();
}

private async Task<bool> EnsureConnectedAsync()
{
    if (_isConnected) return true;

    var tcs = new TaskCompletionSource<bool>();
    _billingClient.StartConnection(
        onConnected: () => { _isConnected = true; tcs.TrySetResult(true); },
        onDisconnected: (_) => { _isConnected = false; tcs.TrySetResult(false); }
    );
    return await tcs.Task;
}

var connected = await EnsureConnectedAsync();
if (!connected) return; // fall back to your normal Play Billing purchase flow

var availability = await _billingClient.IsBillingProgramAvailableAsync();
if (availability != GoogleBillingResponseCode.Ok)
{
    // Not eligible, or a transient failure (see the response code table
    // below). Either way, fall back to your normal Play Billing purchase
    // flow for this purchase.
    return;
}

var reportingDetails = await _billingClient.CreateBillingProgramReportingDetailsAsync();
if (reportingDetails.responseCode != GoogleBillingResponseCode.Ok) return;

var externalTransactionToken = reportingDetails.externalTransactionToken;
// Send this to your backend now, tagged onto the order about to be
// created (see Backend integration below). Don't hold onto it for a
// later purchase.

var launchResponse = await _billingClient.LaunchExternalLink(
    checkoutUrl,
    LinkType.LINK_TO_DIGITAL_CONTENT_OFFER,
    LaunchMode.CALLER_WILL_LAUNCH_LINK
);

if (launchResponse != GoogleBillingResponseCode.Ok) return;

// Google's disclosure was shown and accepted. Now open checkoutUrl
// yourself through your existing Steer Safe checkout provider.

Handle every response code this flow can return:

Reporting compliance: the reporting-relevant deep-link handling is threading the token back. The token is tagged onto the FastSpring order at /encode time (so the webhook can report immediately), and also appended to the checkout URL, so the client can ask the backend to confirm or retry reporting (/reportTransaction) if the webhook hasn't landed yet. That's the only Google-specific addition to your existing return-deep-link handling; everything else about the return trip (re-authenticating, showing a thank-you popup, polling the balance) is standard Steer Safe and isn't detailed further here.

Source: Play Billing, external content links integration guide

Backend integration

These are the four backend additions, used together to tag, report, authenticate, and track each transaction exactly once. Use a load-bearing backend to hold real order data between the webhook firing and the report going out, since a request can arrive before its webhook does, or vice versa.

// Existing /encode handler: add googleExternalTransactionToken to tags
const payload = {
  items: [{ product: productId }],
  tags: {
    playerId,
    googleExternalTransactionToken: externalTransactionToken // from the client
  }
};

async function reportToGoogle(externalTransactionToken: string, order: FastSpringOrderCompletedEvent) {
  const accessToken = await getGoogleAccessToken(); // next step, below
  const externalTransactionId = order.id; // FastSpring's own order id, see gotchas below

  const response = await fetch(
    `https://androidpublisher.googleapis.com/androidpublisher/v3/applications/${PACKAGE_NAME}/externalTransactions` +
    `?externalTransactionId=${encodeURIComponent(externalTransactionId)}`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        // priceMicros is millionths of the currency unit: $4.99 becomes "4990000"
        originalPreTaxAmount: { priceMicros: toPriceMicros(order.subtotal), currency: order.currency },
        originalTaxAmount: { priceMicros: toPriceMicros(order.tax), currency: order.currency },
        transactionTime: new Date(order.changed).toISOString(),
        oneTimeTransaction: { externalTransactionToken },
        userTaxAddress: { regionCode: 'US' }, // this program is US-only, nothing to derive per order
        externalContentLinkDetails: { linkType: 'LINK_TO_DIGITAL_CONTENT_OFFER' } // this program specifically, not externalOfferDetails
      })
    }
  );

  if (!response.ok) {
    // Log it and leave unreported. A webhook redelivery or a scheduled
    // sweep gets another shot at it. Don't throw and fail the whole
    // webhook handler over a Google-side rejection.
    console.error('[reportToGoogle] rejected:', response.status, await response.text());
    return;
  }

  await markReported(externalTransactionToken); // see the tracking step, below
}

function toPriceMicros(amount: number): string {
  return String(Math.round(amount * 1_000_000));
}

import { google } from 'googleapis';

// Module-level, not constructed per call. google-auth-library caches and
// refreshes the resolved access token internally once this has been used.
const auth = new google.auth.GoogleAuth({
  credentials: JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_JSON),
  scopes: ['https://www.googleapis.com/auth/androidpublisher']
});

async function getGoogleAccessToken(): Promise<string> {
  const client = await auth.getClient();
  const { token } = await client.getAccessToken();
  if (!token) {
    throw new Error('Failed to obtain Google access token');
  }
  return token;
}

// { token TEXT PRIMARY KEY, reported_at TIMESTAMPTZ }
async function alreadyReported(token: string): Promise<boolean> {
  const row = await db.get('SELECT reported_at FROM google_reports WHERE token = $1', [token]);
  return !!row?.reported_at;
}

async function markReported(token: string) {
  await db.query('UPDATE google_reports SET reported_at = now() WHERE token = $1', [token]);
}

// Wherever the webhook currently grants the entitlement, add:
if (!(await alreadyReported(externalTransactionToken))) {
  await reportToGoogle(externalTransactionToken, order);
}

A few gotchas worth knowing, that don't fit neatly into a step above:

Source: Play Billing, integrating your backend outside GPB

Repository layout

This section maps out where the Unity client, backend, and build workflow live in the repo.

.
├── Unity-UGS/                  The reference build: Unity game + Node backend + web checkout page
│   ├── Unity/                  Unity 6000.0.59f2 project (Eggblast Arena)
│   ├── Backend/                Express/TypeScript server deployed to Railway (also serves WebCode/)
│   └── ...
└── .github/workflows/          Manual "Generate Build" workflow for Unity targets

The backend also exposes a handful of gameplay-economy routes (/spend, /earn, /earnEggs, /checkLevelUp) and a separate native-purchase-validation route (/validateGooglePurchase) that aren't part of the Google reporting flow described above. See the per-folder READMEs if you need those.

Environment variables

This table covers only the Google-reporting-specific variables. The base Steer Safe integration needs its own set (UGS project and service account, FastSpring RSA private key, and so on); see the Unity-UGS/Backend README for the full list.

Set these in your secure backend, or a local .env.

cd Unity-UGS/Backend && npm install && npm run build && npm start

Building

Build through this script, or the Google steering path gets silently skipped.

Editor/BuildScript.cs sets the scripting define for a variant and builds; the define chooses which store-opening provider is used. Building via the Unity Editor's normal Build Settings window instead (rather than one of BuildScript.cs's -executeMethod entry points) sets none of these defines, so the Google steering path is silently skipped, not broken. Always build through BuildScript.cs (or the CI workflow) if you want to test steering. See the Unity-UGS/Unity README for the full target list.

Testing

Walk through these scenarios to confirm both the eligible and ineligible paths behave correctly, plus safe webhook redelivery.

Use FastSpring's sandbox test card for purchases (4242 4242 4242 4242, any future expiry; the CVV is unique to your account and found in the FastSpring dashboard).

In the Unity Editor, press D while GameplayScene or MainScene is running to simulate the return deep link without a real device or checkout.

Backend: npx tsc --noEmit from Unity-UGS/Backend type-checks the whole server with no build step. There's no automated test suite for either the backend or the Unity client; verification so far has been manual, against a live sandbox order.

Security

These are the security practices specific to the Google reporting layer, on top of your existing Steer Safe security.

Related resources

Start with the base Steer Safe integration this repo extends, then reference these for the Google-specific pieces.

• Unity/UGS and FastSpring checkout integration with Steer Safe™ (start here for the base integration this page extends)
• FastSpring Webhooks overview
• FastSpring Secure Payloads
• Google Play External Content Links, program overview
• Google Play External Content Links, integration guidance
• Google Play External Content Links, enrollment
• FSBuilds GitHub repository