Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hyperx.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldDescription
TypeSocial login, Purchase, or Push.
Providergoogle, apple, facebook, google_play, app_store, one_store, fcm, or apns.
App identifierAndroid package name, iOS bundle ID, or provider app ID.
Public config JSONNon-secret identifiers such as client ID or package name.
Secret payload JSONPrivate key, client secret, or webhook secret.

​
Social Login

After signing in with a provider SDK, pass the token to HyperX. 
var session = await HyperX.Core.Users.LoginSocial(
    provider: "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 Core.Purchases.ValidateJson. HyperX validates the receipt through the provider API using Console credentials. 
var purchase = await HyperX.Core.Purchases.ValidateJson(
    "google_play",
    "gold_pack_100",
    "GPA.1234-5678-9012-34567",
    session.AccessToken,
    "{\"purchase_token\":\"STORE_PURCHASE_TOKEN\",\"app_identifier\":\"com.example.game\"}",
    "{\"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.
ProviderSetup Location
Google PlayReal-time developer notifications and Cloud Pub/Sub push subscription
App StoreApp Store Server Notifications V2 production server URL
ONE StorePNS Notification URL in Developer Center

​
Push Providers

Push requires provider console setup, HyperX credentials, and Unity device token registration. 
await HyperX.Core.Push.RegisterDevice(
    deviceToken,
    "android",
    session.AccessToken,
    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.