Provider Integrations

Provider integrations connect your HyperX project to Google, Apple, Facebook, stores, FCM, and APNs. Secrets are registered in Console and must never be shipped in Unity clients.

Principles

Register credentials from the project Credentials page in Console.
Unity clients send only values they should receive, such as provider tokens, purchase tokens, and device tokens.
Do not include service account private keys, APNs .p8 keys, Facebook app secrets, or webhook secrets in client builds.
If one project has multiple apps for the same provider, pass appIdentifier or receipt_payload.app_identifier.

Common Credential Fields

Field	Description
Type	`Social login`, `Purchase`, or `Push`.
Provider	`google`, `apple`, `facebook`, `google_play`, `app_store`, `one_store`, `fcm`, or `apns`.
App identifier	Android package name, iOS bundle ID, or provider app ID.
Public config JSON	Non-secret identifiers such as client ID or package name.
Secret payload JSON	Private key, client secret, or webhook secret.

After signing in with a provider SDK, pass the token to HyperX.

var session = await HyperX.Core.Users.LoginSocial(
    provider: HyperX.SocialProvider.Google,
    identityToken: googleIdToken,
    country: "US",
    language: "en",
    appIdentifier: "com.example.game"
);

Google

{
  "public_config": {
    "client_id": "google-web-client-id.apps.googleusercontent.com"
  }
}

The Unity client passes an ID token from Google Play Games or Google Sign-In. HyperX checks token signature and audience.

Apple

{
  "public_config": {
    "team_id": "TEAM123",
    "client_id": "com.example.game",
    "key_id": "KEY123"
  },
  "secret_payload": {
    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----"
  }
}

Native iOS/macOS login usually uses the bundle ID as client_id. The Unity client passes the Apple identity token.

Facebook

{
  "public_config": {
    "app_id": "facebook-app-id"
  },
  "secret_payload": {
    "app_secret": "facebook-app-secret"
  }
}

The Unity client passes the Facebook user access token as identityToken. HyperX checks token validity and app ID.

Store Purchase Validation

After a purchase succeeds, call player.ValidatePurchase. HyperX validates the receipt through the provider API using Console credentials.

var purchase = await player.ValidatePurchase(
    "google_play",
    "gold_pack_100",
    "GPA.1234-5678-9012-34567",
    new
    {
        purchase_token = "STORE_PURCHASE_TOKEN",
        app_identifier = "com.example.game"
    },
    new { gold = 100 }
);

Google Play

{
  "public_config": {
    "package_name": "com.example.game"
  },
  "secret_payload": {
    "client_email": "play-api@example.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n",
    "webhook_secret": "shared-webhook-secret"
  }
}

Grant the service account permission to read purchase data through Google Play Developer API. Send the purchase token as receipt_payload.purchase_token or receipt_payload.token.

App Store

{
  "public_config": {
    "issuer_id": "issuer-id",
    "key_id": "KEY123",
    "bundle_id": "com.example.game"
  },
  "secret_payload": {
    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----",
    "webhook_secret": "shared-webhook-secret"
  }
}

Register the App Store Server API issuer ID, key ID, and private key. Send the StoreKit transaction ID as transaction_id.

ONE Store

{
  "public_config": {
    "client_id": "one-store-client-id",
    "package_name": "com.example.game"
  },
  "secret_payload": {
    "client_secret": "one-store-client-secret",
    "webhook_secret": "shared-webhook-secret"
  }
}

Register the ONE store client ID and client secret. Send the purchase token as receipt_payload.purchase_token or receipt_payload.token.

Refund and Cancellation Webhooks

Providers send refund, cancel, and revoke events to the HyperX webhook URL. HyperX deduplicates events and marks matched purchases as refunded.

https://core.hyperx.dev/v1/purchases/webhooks/{project_code}/{provider}?app_identifier={app_identifier}

Prefer the x-hyperx-webhook-secret header. If the provider console does not support custom headers, use the webhook_secret query parameter.

Provider	Setup Location
Google Play	Real-time developer notifications and Cloud Pub/Sub push subscription
App Store	App Store Server Notifications V2 production server URL
ONE Store	PNS Notification URL in Developer Center

Push Providers

Push requires provider console setup, HyperX credentials, and Unity device token registration.

await player.RegisterPushDevice(
    deviceToken,
    HyperX.PushPlatform.Android,
    optIn: true,
    locale: "en-US",
    timezone: "America/Los_Angeles"
);

FCM

{
  "public_config": {
    "firebase_project_id": "firebase-project-id",
    "android_package_name": "com.example.game"
  },
  "secret_payload": {
    "client_email": "firebase-adminsdk@example.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"
  }
}

Register a service account with Firebase Cloud Messaging HTTP v1 permission. The Android package name must match Firebase, Unity Player Settings, and HyperX.

APNs

{
  "public_config": {
    "team_id": "TEAM123",
    "key_id": "KEY123",
    "bundle_id": "com.example.game"
  },
  "secret_payload": {
    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----"
  }
}

Enable Push Notifications capability in Apple Developer and register the APNs Auth Key. The iOS bundle ID must match the Unity iOS build and HyperX credential.

Campaign Delivery

Operators create and send push campaigns from Console. A campaign target can include platform, environment, app_identifier, limit, max_attempts, and validate_only. HyperX sends Android devices through FCM and iOS devices through APNs, retries retryable provider failures up to the campaign max_attempts boundary, and records one delivery result per device. Console shows delivery status, attempts, provider message IDs, provider errors, and invalid-token cleanup. When FCM or APNs reports an invalid device token, HyperX marks that device as opted out so future campaigns do not keep retrying a stale token.

Checklist

Provider secrets are not included in Unity builds.
Package name, bundle ID, and client ID match the released app.
Social tokens are fresh short-lived tokens from provider SDKs.
Purchase requests use real store transaction_id and purchase token values.
Call RegisterDevice again when the push token changes.
Check Console campaign delivery diagnostics after production sends.

Getting Started

SDK Basics

Web API

Data and Content

Operations and Integrations

Social and Realtime

Provider Integrations

Principles

Common Credential Fields

Google

Apple

Facebook

Store Purchase Validation

Google Play

App Store

ONE Store

Refund and Cancellation Webhooks

Push Providers

FCM

APNs

Campaign Delivery

Checklist

​Principles

​Common Credential Fields

​Social Login

​Google

​Apple

​Facebook

​Store Purchase Validation

​Google Play

​App Store

​ONE Store

​Refund and Cancellation Webhooks

​Push Providers

​FCM

​APNs

​Campaign Delivery

​Checklist

Principles

Common Credential Fields

Social Login

Google

Apple

Facebook

Store Purchase Validation

Google Play

App Store

ONE Store

Refund and Cancellation Webhooks

Push Providers

FCM

APNs

Campaign Delivery

Checklist