메인 콘텐츠로 건너뛰기
Provider 연동은 Google, Apple, Facebook, 스토어, FCM, APNs 같은 외부 서비스를 HyperX 프로젝트와 연결하는 설정입니다. 비밀키는 Console에만 등록하고 Unity 클라이언트에는 넣지 않습니다.

​
기본 원칙

  • 자격증명은 Console의 프로젝트 Credentials 화면에서 등록합니다.
  • Unity 클라이언트는 provider token, purchase token, device token처럼 클라이언트가 받아야 하는 값만 HyperX에 전달합니다.
  • 서비스 계정 private key, APNs .p8, Facebook app secret, webhook secret은 클라이언트 빌드에 포함하지 않습니다.
  • 같은 provider를 여러 앱에서 쓰는 경우 appIdentifier 또는 receipt_payload.app_identifier로 앱을 구분합니다.

​
자격증명 공통 필드

필드설명
TypeSocial login, Purchase, Push 중 하나입니다.
Providergoogle, apple, facebook, google_play, app_store, one_store, fcm, apns 중 하나입니다.
App identifierAndroid package name, iOS bundle ID, provider 앱 ID처럼 앱을 구분하는 값입니다.
Public config JSONclient ID, package name처럼 공개되어도 되는 설정입니다.
Secret payload JSONprivate key, client secret, webhook secret처럼 비밀로 보관해야 하는 값입니다.

​
소셜 로그인

Unity에서 provider SDK로 로그인한 뒤 받은 토큰을 HyperX로 전달합니다. 
var session = await HyperX.Core.Users.LoginSocial(
    provider: HyperX.SocialProvider.Google,
    identityToken: googleIdToken,
    country: "KR",
    language: "ko",
    appIdentifier: "com.example.game"
);

​
Google

{
  "public_config": {
    "client_id": "google-web-client-id.apps.googleusercontent.com"
  }
}
Unity 클라이언트는 Google Play Games 또는 Google Sign-In SDK에서 받은 ID token을 전달합니다. HyperX는 토큰 서명과 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-----"
  }
}
iOS/macOS 네이티브 로그인은 보통 bundle ID를 client_id로 사용합니다. Unity 클라이언트는 Apple identity token을 전달합니다.

​
Facebook

{
  "public_config": {
    "app_id": "facebook-app-id"
  },
  "secret_payload": {
    "app_secret": "facebook-app-secret"
  }
}
Unity 클라이언트는 Facebook user access token을 identityToken으로 전달합니다. HyperX는 Facebook 앱 ID와 토큰 유효성을 확인합니다.

​
스토어 결제 검증

결제 완료 후 SDK는 player.ValidatePurchase를 호출합니다. HyperX는 Console에 등록된 스토어 자격증명으로 provider API에 검증 요청을 보냅니다. 
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"
  }
}
Google Play Developer API 접근 권한을 설정하고 결제 조회 권한을 서비스 계정에 부여합니다. Unity 결제 후 purchase token을 receipt_payload.purchase_token 또는 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"
  }
}
App Store Server API key의 issuer ID, key ID, private key를 등록합니다. StoreKit transaction ID를 transaction_id로 전달하면 HyperX가 구매를 검증합니다.

​
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"
  }
}
ONE store client ID와 client secret을 등록합니다. Unity 결제 후 purchase token을 receipt_payload.purchase_token 또는 receipt_payload.token으로 전달합니다.

​
환불과 취소 webhook

Provider가 환불, 취소, 회수 이벤트를 HyperX webhook URL로 보내면 HyperX는 중복 이벤트를 제거하고 매칭되는 구매를 refunded로 표시합니다. 
https://core.hyperx.dev/v1/purchases/webhooks/{project_code}/{provider}?app_identifier={app_identifier}
가능하면 provider 요청에 x-hyperx-webhook-secret 헤더를 추가하세요. provider 콘솔이 custom header를 지원하지 않으면 webhook_secret query parameter를 사용할 수 있습니다.
Provider설정 위치
Google PlayReal-time developer notifications(RTDN)와 Cloud Pub/Sub push subscription
App StoreApp Store Server Notifications V2 production server URL
ONE storeDeveloper Center의 PNS Notification URL

​
푸시 provider

푸시 알림은 provider 콘솔 설정, HyperX 자격증명, Unity 디바이스 토큰 등록이 모두 맞아야 동작합니다. 
await player.RegisterPushDevice(
    deviceToken,
    HyperX.PushPlatform.Android,
    optIn: true,
    locale: "ko-KR",
    timezone: "Asia/Seoul"
);

​
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"
  }
}
Firebase Cloud Messaging HTTP v1 권한이 있는 service account를 등록합니다. Android package name은 Firebase 앱, Unity Player Settings, HyperX credential에서 모두 같아야 합니다.

​
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-----"
  }
}
Apple Developer에서 Push Notifications capability를 활성화하고 APNs Auth Key를 등록합니다. iOS bundle ID는 Unity iOS 빌드와 HyperX credential에서 같아야 합니다.

​
캠페인 전송

운영자는 Console에서 푸시 캠페인을 생성하고 전송합니다. 캠페인 target에는 platform, environment, app_identifier, limit, max_attempts, validate_only를 넣을 수 있습니다. HyperX는 Android 디바이스는 FCM으로, iOS 디바이스는 APNs로 전송하고, 재시도 가능한 provider 실패는 캠페인의 max_attempts 경계 안에서만 재시도합니다. 전송 결과는 디바이스별로 기록됩니다. Console에서는 전송 상태, 시도 횟수, provider message ID, provider 오류, invalid token 정리를 확인할 수 있습니다. FCM 또는 APNs가 유효하지 않은 디바이스 토큰을 반환하면 HyperX는 해당 디바이스를 opt-out 처리해 이후 캠페인에서 같은 stale token을 반복 전송하지 않습니다.

​
점검 체크리스트

  • Unity 빌드에 provider secret이 포함되어 있지 않습니다.
  • package name, bundle ID, client ID가 실제 출시 앱과 일치합니다.
  • 소셜 로그인 토큰은 클라이언트에서 새로 받은 짧은 수명의 token입니다.
  • 결제 검증 요청의 transaction_id와 purchase_token이 실제 스토어 구매 값입니다.
  • 푸시 토큰이 갱신되면 RegisterDevice를 다시 호출합니다.
  • production 캠페인 전송 후 Console delivery diagnostics를 확인합니다.