메인 콘텐츠로 건너뛰기

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 연동은 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: "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는 Core.Purchases.ValidateJson을 호출합니다. HyperX는 Console에 등록된 스토어 자격증명으로 provider API에 검증 요청을 보냅니다. 
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"
  }
}
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 HyperX.Core.Push.RegisterDevice(
    deviceToken,
    "android",
    session.AccessToken,
    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에서 같아야 합니다.

​
점검 체크리스트

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