페이 스테이션을 Firebase 인증과 함께 사용하는 방법
애플리케이션에서 Firebase를 사용하여 사용자 인증을 이미 구현한 경우 Firebase에서 결제 토큰을 생성한 다음 이를 애플리케이션의 클라이언트 측에 전달하여 결제 UI를 열 수 있습니다.
이 연동 옵션을 사용하는 경우 구매 시 비용을 지불하는 사용자의 국가 및 통화를 결정하는 로직을 독립적으로 구현해야 합니다.
연동 절차:
- 관리자 페이지에 등록한 후 새 프로젝트를 생성합니다. 이후 단계에서 생성하는 프로젝트의 ID가 필요합니다.
- 카탈로그 설정 방법:
- 엑솔라 측에서 아이템 카탈로그를 생성합니다. 아이템을 수동으로 추가하거나 Google Play 또는 PlayFab에서 가져올 수 있습니다.
Store 라이브러리를 사용하여 애플리케이션의 클라이언트 측에서 카탈로그 가져오기 및 표시를 구현합니다.
- 아이템 구매 설정 방법:
- Firebase 클라우드 함수를 사용하여 애플리케이션의 클라이언트 측에서 사용자 및 아이템 데이터로 주문을 생성합니다.
Payments 라이브러리를 사용하여 애플리케이션의 클라이언트 측에서 결제 UI 열기를 구현합니다.
연동을 완료하고 실제 결제 수락을 시작하려면 엑솔라와 라이선스 계약을 체결해야 합니다.
모든 연동 단계에서 라이선스 계약에 서명할 수 있지만, 검토 절차에 최대 3일(영업일 기준)이 소요될 수 있다는 점에 유의해 주세요.
예를 들어 Firebase 인증과 Pay Station의 결합하는 사례를 샘플 웹 애플리케이션을 사용하여 구현해 보세요. 샘플 웹 애플리케이션의 소스 코드는 GitHub에서 확인할 수 있습니다.
프로젝트 생성
관리자 페이지에 등록하기
관리자 페이지는 엑솔라 기능을 구성하고 분석과 트랜잭션 작업에 사용하는 기본 도구입니다.
등록할 때 지정한 회사 및 애플리케이션에 대한 데이터는 엑솔라와의 라이선스 계약 초안을 생성하고 적합한 솔루션 추천을 생성하는 데 사용됩니다. 나중에 해당 데이터를 변경할 수 있지만 등록할 때 올바른 데이터를 제공하면 라이선스 계약 체결 프로세스가 빨라집니다.
등록하려면 관리자 페이지로 이동한 후 계정을 생성합니다.
관리자 페이지의 암호는 라틴 문자, 숫자 및 특수 문자로 구성될 수 있으며 다음 최소 요건을 충족해야 합니다.
- 8자 이상
- 숫자 하나 이상
- 대문자 하나 이상
- 소문자 하나 이상
암호 보안을 위해 다음을 권장합니다.
- 90일에 한 번 이상 암호 변경
- 기존 계정 암호에 사용한 마지막 4개의 문자와 일치하지 않는 새 암호 사용
- 다른 곳에서 사용하는 암호와 일치하지 않는 고유한 암호 사용
- 쉽게 액세스할 수 없는 곳에 암호 저장
- 암호 관리 프로그램을 사용하여 암호 저장
관리자 페이지는 2단계 인증을 사용하며 인증을 시도할 때마다 확인 코드를 전송합니다.
관리자 페이지에서 프로젝트 생성
애플리케이션이 여러 개 있는 경우 각 애플리케이션에 대한 별도의 프로젝트를 생성하는 것이 좋습니다. 프로젝트 생성 시 지정한 데이터를 기반으로 엑솔라는 적합한 솔루션에 대한 권장 사항을 생성합니다.
새 프로젝트를 생성하는 방법:
- 관리자 페이지를 엽니다.
- 사이드 메뉴에서 새 프로젝트 만들기를 클릭합니다.
- 프로젝트 이름을 영문으로 입력합니다(필수).
- 게임을 출시하는 플랫폼을 하나 또는 여러 개 선택합니다(필수).
- 게임 링크를 추가합니다. 게임에 아직 웹사이트가 없는 경우 게임에 대한 정보가 포함된 소스 링크를 추가합니다(필수).
- 게임 엔진을 선택합니다.
- 사용 중이거나 사용할 예정인 수익화 옵션을 선택합니다.
- 게임이 이미 출시되었는지 여부를 지정합니다. 게임이 아직 출시되지 않은 경우 출시 예정일을 지정합니다.
- 프로젝트 생성을 클릭합니다. 추천하는 엑솔라 제품이 있는 페이지가 표시됩니다.
연동을 처리하는 동안 프로젝트 이름 옆의 관리자 페이지에서 확인할 수 있는 프로젝트 ID를 제공해야 합니다.
카탈로그 설정하기
관리자 페이지에서 아이템 생성하기
엑솔라 측에서 카탈로그를 생성해야 합니다. 아이템 수동으로 추가하기나 Google Play 또는 PlayFab에서 가져오기를 수행할 수 있습니다. Google Play에서 가져오기를 수행할 경우 한 번에 최대 100개의 아이템을 가져올 수 있습니다.
이 지침은 가상 아이템의 기본 설정 단계를 제공합니다. 나중에 카탈로그에 다른 아이템(인게임 재화, 번들, 게임 키)을 추가하고, 아이템 그룹을 생성하고, 프로모션 캠페인, 지역별 가격 등을 설정할 수 있습니다.
카탈로그에 기본 설정이 있는 가상 아이템을 추가하는 방법:
- 관리자 페이지에서 프로젝트를 엽니다.
- 사이드 메뉴에서 스토어를 클릭합니다.
- 가상 아이템 창에서 연결을 클릭합니다.
- 드롭다운 메뉴에서 아이템 생성을 선택합니다.
- 다음 필드에서 아이템의 기본 설정을 설정합니다.
- 이미지(선택 사항)
- SKU(아이템 고유 ID)
- 아이템 이름
- 설명(선택 사항)
- 아이템 가격 지정:
- 실제 통화 가격 토글을 온으로 설정합니다.
- 기본 통화 필드에서 통화를 변경하고(선택 사항) 아이템 가격을 지정합니다.
- 기본 통화 필드에서 통화를 변경한 경우 실제 통화 가격 필드에서 동일한 통화를 선택합니다.
- 아이템 상태를 사용 가능으로 변경합니다.
- 아이템 생성을 클릭합니다.
애플리케이션의 클라이언트 측에 카탈로그 표시하기
- 프로젝트에
Store 라이브러리를 추가합니다. 이렇게 하려면build.gradle
를 열고 종속성 섹션에 다음 줄을 추가합니다.
implementation("com.xsolla.android:store:latest.release")
- 애플리케이션의 클라이언트 측에서 제품 카탈로그를 표시하는 UI를 추가합니다.
- 엑솔라 서버로부터 아이템 카탈로그를 요청하는 기능을 구현합니다.
XStore.getVirtualItems
메소드를 사용합니다. 다른 예시(샘플 웹 애플리케이션의
- kotlin
package com.xsolla.androidsample
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.widget.Toast
import androidx.recyclerview.widget.LinearLayoutManager
import androidx.recyclerview.widget.RecyclerView
import com.xsolla.android.store.XStore
import com.xsolla.android.store.callbacks.GetVirtualItemsCallback
import com.xsolla.android.store.entity.response.items.VirtualItemsResponse
import com.xsolla.androidsample.adapter.BuyItemAdapter
class StoreActivity : AppCompatActivity() {
private lateinit var itemsView: RecyclerView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_store)
XStore.init(<projectId>)
initUI()
loadVirtualItems()
}
private fun initUI() {
itemsView = findViewById(R.id.buy_recycler_view)
itemsView.layoutManager = LinearLayoutManager(this)
}
private fun loadVirtualItems() {
val parentActivity = this
XStore.getVirtualItems(object : GetVirtualItemsCallback {
override fun onSuccess(response: VirtualItemsResponse) {
itemsView.adapter = BuyItemAdapter(parentActivity, response.items.filter { item -> item.virtualPrices.isEmpty() && !item.isFree })
}
override fun onError(throwable: Throwable?, errorMessage: String?) {
showNotificationMessage(errorMessage ?: throwable?.javaClass?.name ?: "Error")
}
})
}
private fun showNotificationMessage(message: String) {
Toast.makeText(
baseContext,
message,
Toast.LENGTH_SHORT,
).show()
}
}
스크립트의 XStore.init()
초기화 블록에서 프로젝트 이름 옆의 관리자 페이지에서 확인할 수 있는 프로젝트 ID를 지정합니다.
아이템 구매 설정하기
클라우드 함수를 사용하여 주문 생성하기
엑솔라 측에서 사용자 및 아이템 데이터로 주문을 생성하려면 구매용 결제 토큰 생성 API 호출을 사용하는 클라우드 함수를 프로젝트에 추가합니다. 이 호출은 결제 UI를 열고 구매를 하는 데 필요한 결제 토큰을 반환합니다.
제한 사항:
- 결제 토큰을 요청할 때 사용자 국가 또는 사용자의 IP 주소를 전달해야 합니다.
- 토큰에서 통화를 전달하지 않으면 국가에 따라 결정됩니다.
- 토큰에서 통화를 전달하면 사용자가 이 통화로 결제합니다.
프로젝트에 클라우드 함수를 추가하는 방법:
- Firebase CLI(명령줄 인터페이스)를 설치합니다. 이렇게 하려면 다음 CLI 명령을 실행합니다.
npm install -g firebase-tools
- 프로젝트를 Firebase 프로젝트에 연결하려면 다음 CLI 명령을 실행하여 Firebase 프로젝트를 초기화해야 합니다.
firebase init functions
- 설치 프로그램의 지침에 따라 설정을 구성합니다.
- 기존 코드베이스를 선택합니다.
- 클라우드 함수 생성에 사용할 언어로 JavaScript를 지정합니다.
- 종속성을 설치합니다.
functions/index.js
를 열고 이를 수정합니다.
- javascript
// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const functions = require('firebase-functions/v1');
const projectId = <projectId>;
const apiKey = <apiKey>;
exports.getXsollaPaymentToken = functions.https.onRequest((req, res) => {
const requestBody = req.body;
if (!requestBody) {
res.status(400).send('Request body is missing');
return;
}
const userId = requestBody.data.uid;
const email = requestBody.data.email;
const sku = requestBody.data.sku;
const returnUrl = requestBody.data.returnUrl;
const payload = {
user: {
id: {value: userId},
name: {
value: email
},
email: {
value: email
},
country: {
value: 'US',
allow_modify: false
}
},
purchase: {
items: [
{
sku: sku,
quantity: 1
}
]
},
sandbox: true,
settings: {
language: 'en',
currency: 'USD',
return_url: returnUrl,
ui: {
theme: '63295aab2e47fab76f7708e3'
}
}
}
let url = "https://store.xsolla.com/api/v3/project/" + projectId.toString() + "/admin/payment/token";
fetch(
url,
{
method: "POST",
headers: {
'Content-Type': 'application/json',
Authorization: 'Basic ' + btoa(`${projectId}:${apiKey}`)
},
body: JSON.stringify(payload)
},
)
.then(xsollaRes => {
// Handle the response data
if (xsollaRes.ok) {
return xsollaRes.json();
} else {
throw new Error(`HTTP request failed with status ${xsollaRes.status} and statusText: ${xsollaRes.statusText}`)
}
})
.then(data => {
res.send(JSON.stringify(data));
})
.catch(error => {
res.send("Error = " + error);
});
});
exports.webhookFakeResponse = functions.https.onRequest((request, response) => {
response.status(200).send()
})
- 스크립트에서 변수 값을 지정합니다.
projectId
- 프로젝트 이름 옆의 관리자 페이지에서 찾을 수 있는 프로젝트 ID입니다.
apiKey
- API 키. 생성할 때 한 번만 관리자 페이지에 표시되며 따로 저장하고 관리해야 합니다. 다음 섹션에서 새 키를 생성할 수 있습니다.- 회사 설정 > API 키
- 프로젝트 설정 > API 키
- 에뮬레이터로 클라우드 함수를 테스트하려면 다음 CLI 명령을 실행합니다.
firebase emulators:start
- 클라우드 함수를 실행한 후 애플리케이션의 클라이언트 측에서 다음 메소드를 호출할 수 있습니다.
- 로컬에서 메소드를 호출하려면
https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken
및https://localhost:5001/{firebase-project-id}/us-central1/webhookFakeResponse
URL을 사용해야 하며, 여기서{firebase-project-id}
는 Firebase 프로젝트 ID입니다(Firebase 콘솔 > 프로젝트 설정 > 프로젝트 ID).
- 프로덕션에서 클라우드 함수를 배포하려면 다음 CLI 명령을 실행합니다.
firebase deploy --only functions
- 프로덕션이 배포되면
https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken
및https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse
URL을 통해 메소드를 호출할 수 있으며, 여기서{firebase-project-id}
는 Firebase 프로젝트 ID입니다(Firebase 콘솔 > 프로젝트 설정 > 프로젝트 ID). 프로덕션에서 이 기능을 실행하는 방법에 대한 자세한 내용은 Firebase 문서를 참조해 주세요.
결제 UI 시작 설정하기
- 프로젝트에
Payments 라이브러리를 추가합니다. 이렇게 하려면build.gradle
를 열고 종속성 섹션에 다음 줄을 추가합니다.
implementation("com.xsolla.android:payments:latest.release")
AndroidManifest.xml
을 열고 인터넷 액세스 권한을 추가합니다.
- xml
<uses-permission android:name="android.permission.INTERNET" />
- 주문을 생성하고(클라우드 함수의
XStore.getXsollaPaymentToken
메소드 호출) 수신한 결제 토큰으로 결제 UI를 여는(XPayments.createIntentBuilder()
클래스) 로직을 추가합니다.
getXsollaPaymentToken
메소드를 호출하려면 다음 URL 중 하나를 제공합니다. 여기서{firebase-project-id}
는 Firebase 프로젝트 ID입니다(Firebase 콘솔 > 프로젝트 설정 > 프로젝트 ID).- 로컬 액세스의 경우 -
https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken
- 프로덕션 액세스용 -
https://us-central1-{firebase-project-id}.cloudfunctions.net/getXsollaPaymentToken
- 로컬 액세스의 경우 -
예시(샘플 웹 애플리케이션의
- kotlin
package com.xsolla.androidsample.adapter
import android.R.attr.duration
import android.os.Handler
import android.os.Looper
import android.view.LayoutInflater
import android.view.ViewGroup
import android.widget.Toast
import androidx.recyclerview.widget.RecyclerView
import com.bumptech.glide.Glide
import com.xsolla.android.payments.XPayments
import com.xsolla.android.payments.data.AccessToken
import com.xsolla.android.store.entity.response.items.VirtualItemsResponse
import com.xsolla.androidsample.R
import com.xsolla.androidsample.StoreActivity
import org.json.JSONObject
import java.io.BufferedReader
import java.io.BufferedWriter
import java.io.OutputStream
import java.io.OutputStreamWriter
import java.net.HttpURLConnection
import java.net.URL
class BuyItemAdapter(private val parentActivity: StoreActivity, private val items: List<VirtualItemsResponse.Item>) :
RecyclerView.Adapter<BuyItemViewHolder>() {
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): BuyItemViewHolder {
return BuyItemViewHolder( LayoutInflater.from(parent.context)
.inflate(R.layout.buy_item_sample, parent, false))
}
override fun onBindViewHolder(holder: BuyItemViewHolder, position: Int) {
val item = items[position]
Glide.with(holder.view).load(item.imageUrl).into(holder.itemImage)
holder.itemName.text = item.name
holder.itemDescription.text = item.description
var priceText: String
if(item.virtualPrices.isNotEmpty()) {
priceText = item.virtualPrices[0].getAmountRaw() + " " + item.virtualPrices[0].name
} else {
priceText = item.price?.getAmountRaw() + " " + item.price?.currency.toString()
}
holder.itemPrice.text = priceText
holder.itemButton.setOnClickListener {
Thread {
purchase(item.sku!!)
}.start()
}
}
private fun purchase(sku: String) {
val uid = parentActivity.intent.getStringExtra("uid")
val email = parentActivity.intent.getStringExtra("email")
val jsonBody = JSONObject()
jsonBody.put("data", JSONObject().apply {
put("uid", uid)
put("email", email)
put("sku", sku)
put("returnUrl", "app://xpayment." + parentActivity.packageName)
})
val connection = URL(https://localhost:5001/{firebase-project-id}/us-central1/getXsollaPaymentToken).openConnection() as HttpURLConnection
connection.requestMethod = "POST"
connection.setRequestProperty("Content-Type", "application/json")
connection.doOutput = true
val outputStream: OutputStream = connection.outputStream
val writer = BufferedWriter(OutputStreamWriter(outputStream))
writer.write(jsonBody.toString())
writer.flush()
writer.close()
val responseCode = connection.responseCode
if (responseCode == HttpURLConnection.HTTP_OK) {
val response = connection.inputStream.bufferedReader().use(BufferedReader::readText)
connection.disconnect()
val jsonObject = JSONObject(response)
val token = jsonObject.getString("token")
val orderId = jsonObject.getString("order_id")
val intent = XPayments.createIntentBuilder(parentActivity)
.accessToken(AccessToken(token))
.isSandbox(true)
.build()
parentActivity.startActivityForResult(intent, 1)
} else {
Handler(Looper.getMainLooper()).post {
showNotificationMessage("HTTP request failed with error: $responseCode")
}
}
}
override fun getItemCount() = items.size
private fun showNotificationMessage(message: String) {
Toast.makeText(
parentActivity,
message,
Toast.LENGTH_SHORT,
).show()
}
}
- 결제 결과를 처리하는
onActivityResult()
메소드를 추가합니다.
예시(샘플 웹 애플리케이션의
- kotlin
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
if (requestCode == 1) {
val (status, _) = XPayments.Result.fromResultIntent(data)
when (status) {
XPayments.Status.COMPLETED -> showNotificationMessage("Payment completed")
XPayments.Status.CANCELLED -> showNotificationMessage("Payment canceled")
XPayments.Status.UNKNOWN -> showNotificationMessage("Payment error")
}
}
}
주문 상태 추적 설정하기
주문 상태 추적은 결제가 성공적으로 이루어졌는지 확인하고 사용자에게 아이템을 제공할 때 필요합니다.
클라이언트 측에서 주문 상태 가져오기
애플리케이션의 클라이언트 측에서 주문 상태 변경 사항을 구독하려면 XStore.getOrderStatus
메소드를 호출하고 다음 매개 변수를 메소드에 전달합니다.
listener
-OrderStatusListener
유형의 리스너 개체입니다.orderId
- 쇼핑 장바구니, 원클릭 구매 또는 인게임 재화 구매를 통해 구매 시 받은 주문 ID입니다.
메소드 작동 방식에 대한 자세한 내용은 주문 상태 추적 섹션을 참조해 주세요.
서버 측에서 주문 상태 가져오기
엑솔라 측에서 웹훅을 구성하는 방법:
- 관리자 페이지에서 프로젝트를 엽니다.
- 사이드 메뉴에서 프로젝트 설정을 클릭하고 웹훅 섹션으로 이동합니다.
- 웹훅 서버 필드에서 엑솔라가 웹훅을 전송할 URL을 입력합니다.
테스트를 위해 https://us-central1-{firebase-project-id}.cloudfunctions.net/webhookFakeResponse
를 지정할 수 있으며, 여기서 {firebase-project-id}
는 Firebase 프로젝트 ID입니다(Firebase 콘솔 > 프로젝트 설정 > 프로젝트 ID). 이 경우에는 Firebase가 웹훅의 성공적인 처리를 시뮬레이션합니다. 실제 프로젝트에서는 구매 유효성 검사 로직을 추가해야 합니다.
웹훅을 테스트하기 위해 webhook.site와 같은 전용 사이트나 ngrok과 같은 플랫폼을 선택할 수도 있습니다.
- 비밀 키 필드의 값을 복사하여 저장합니다. 이 키는 기본값으로 생성되며 웹훅 서명에 사용됩니다. 변경하려면 업데이트 아이콘을 클릭합니다.
- 웹훅 사용을 클릭합니다.
오자 또는 기타 텍스트 오류를 찾으셨나요? 텍스트를 선택하고 컨트롤+엔터를 누르세요.