> ## 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

> Register external provider credentials for social login, store purchases, and push.

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.                                            |

## Social Login

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

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

### Google

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```cs theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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`.

```text theme={null}
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.

```cs theme={null}
await player.RegisterPushDevice(
    deviceToken,
    HyperX.PushPlatform.Android,
    optIn: true,
    locale: "en-US",
    timezone: "America/Los_Angeles"
);
```

### FCM

```json theme={null}
{
  "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

```json theme={null}
{
  "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.