通行證 | 文件 - Roblox 創作者中心

通行證允許您向用戶收取一次性 Robux 費用，以獲取遊戲內的特殊特權，例如進入受限區域、遊戲內角色物品或永久增益。

對於玩家可能會重複購買的物品，如藥水、暫時增益或遊戲內貨幣，請參見開發者產品。

創建通行證

在創建通行證之前，請確保您的遊戲已被發布，並且可以在 Roblox 上訪問。

要創建通行證：

前往創建並選擇一個遊戲。
轉到貨幣化 ⟩ 通行證。
點擊創建通行證。
上傳一個用作通行證圖標的圖像。請確保圖像不超過 512x512 像素，並且不包含圓形邊界外的主要細節，並且格式為 .jpg、.png 或 .bmp。
為通行證輸入名稱和描述。
為通行證選擇一個類別。該類別用於組織您遊戲內商店的物品。
點擊創建通行證。

如果您想將通行證用作隨機獎勵，請查閱隨機虛擬物品政策。

獲取通行證 ID

要使用腳本，您需要一個通行證 ID。獲取通行證 ID 的方法：

轉到貨幣化 ⟩ 通行證。
鼠標懸停在通行證縮略圖上，單擊 ⋯ 按鈕，然後從上下文菜單中選擇複製資產 ID。

銷售通行證

自 2026 年 5 月 30 日起，跨遊戲通行證銷售將被禁用。如果您的遊戲依賴跨遊戲銷售機制，我們建議在此日期之前集成 Robux 轉移以避免服務中斷。

如果您使用價格優化，請確保將腳本放在 LocalScript 中，以便用戶看到個性化的通行證價格。

您可以通過兩種方式銷售通行證：

在您的遊戲內
在您的遊戲外

在您的遊戲內

要在遊戲內實施和銷售通行證，請調用 MarketplaceService 函數。

使用 GetProductInfo() 獲取通行證的信息，如名稱和價格，然後將該通行證顯示給用戶。您可以在遊戲的市場中銷售通行證。例如，對於通行證，第二個參數必須是 Enum.InfoType.GamePass。


local MarketplaceService = game:GetService("MarketplaceService")

-- 用您的通行證 ID 替換佔位符 ID
local productId = 000000

local success, productInfo = pcall(function()
	return MarketplaceService:GetProductInfo(productId, Enum.InfoType.GamePass)
end)


if success and productInfo then
	-- 檢查產品是否在銷售中
	if productInfo.IsForSale then
	-- 顯示產品信息
	-- 用用戶界面代碼替換打印語句以顯示通行證
  	print("通行證名稱: " .. productInfo.Name)
  	print("Robux 價格: " .. productInfo.PriceInRobux)
  	print("描述: " .. productInfo.Description)
	else
		print("此產品未在銷售中")
	end
end

使用 PromptGamePassPurchase() 在用戶的庫中尚未擁有通行證的情況下提示購買通行證。當用戶執行按鈕按下或與 NPC 供應商交談等操作時，可以調用此函數。


local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")

-- 用您的通行證 ID 替換佔位符 ID
local passID = 0000000

-- 提示購買通行證
local function promptPurchase()
	local player = Players.LocalPlayer
	local hasPass = false

	local success, message = pcall(function()
		hasPass = MarketplaceService:UserOwnsGamePassAsync(player.UserId, passID)
	end)

	if not success then
		warn("檢查玩家是否擁有通行證時出錯: " .. tostring(message))
		return
	end

	if hasPass then
		-- 顯示一條消息告訴用戶他們已經擁有該通行證
	else
		-- 提示購買通行證
		MarketplaceService:PromptGamePassPurchase(player, passID)
	end
end

使用 PromptGamePassPurchaseFinished 來處理完成的通行證提示和購買，並為用戶分配與通行證相關的特權。

將腳本放在 ServerScriptService 中，讓服務器處理用戶的通行證特權。


local MarketplaceService = game:GetService("MarketplaceService")

-- 用您的通行證 ID 替換佔位符 ID
local passID = 0000000  -- 將此更改為您的通行證 ID

-- 處理已完成的提示和購買
local function onPromptPurchaseFinished(player, purchasedPassID, purchaseSuccess)
	if purchaseSuccess and purchasedPassID == passID then
		print(player.Name .. " 購買了 ID 為 " .. passID .. " 的通行證")
		-- 分配用戶與通行證相關的能力或獎勵
	end
end

-- 連接 PromptGamePassPurchaseFinished 事件到該函數
MarketplaceService.PromptGamePassPurchaseFinished:Connect(onPromptPurchaseFinished)

雖然 Roblox 本身並不記錄特定用戶的通行證購買歷史，但您可以請求下載銷售數據。如果您想跟踪用戶特定的購買歷史，則有責任存儲數據。

在您的遊戲外

要在遊戲詳細頁面的商店標籤上銷售通行證：

前往貨幣化 ⟩ 通行證。
鼠標懸停在通行證上，然後單擊 ⋯ 菜單。
選擇您想要銷售的通行證。
選擇銷售。
啟用商品上架切換。
在 Robux 價格字段中，輸入您希望向用戶收取的通行證金額。您輸入的價格影響您每次銷售所賺取的 Robux。最低價格為 1 Robux，最高價格為 10 億 Robux。
點擊保存更改。該通行證將在遊戲詳細頁面的商店標籤上顯示。

分配通行證特權

您必須手動分配購買通行證的用戶的特權。要做到這一點，請在用戶加入遊戲時使用 PlayerAdded 來檢查他們是否已經擁有通行證並分配通行證特權。

將腳本放在 ServerScriptService 中，讓服務器處理用戶的通行證特權。


local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")

-- 用您的通行證 ID 替換佔位符 ID
local passID = 0000000

local function onPlayerAdded(player)
	local hasPass = false

	-- 檢查用戶是否已擁有通行證
	local success, message = pcall(function()
		hasPass = MarketplaceService:UserOwnsGamePassAsync(player.UserId, passID)
	end)

	if not success then
		-- 發出警告並退出函數
		warn("檢查玩家是否擁有通行證時出錯: " .. tostring(message))
		return
	end

	if hasPass then
		-- 分配用戶與通行證相關的能力或獎勵
		print(player.Name .. " 擁有 ID 為 " .. passID .. " 的通行證")
	end
end

-- 連接 PlayerAdded 事件到該函數
Players.PlayerAdded:Connect(onPlayerAdded)

個性化您的遊戲內商店

您可以使用產品智能 API 來對通行證進行排序和推薦，以便向用戶展示個性化的推薦。個性化您的遊戲內商店有助於將最相關的物品顯示給每個用戶，提升參與度和收入。通過根據用戶偏好定制通行證，您可以改善其發現性，提高轉換率，並解鎖新的貨幣化機會。

對銷售通行證進行排序

RankProductsAsync 接受一個產品 ID 列表並返回這些產品的個性化有序列表。您可以使用這個方法在遊戲內商店中為您的用戶提供個性化的商品推薦。

由於 RankProductsAsync 具有嚴格的速率限制，您應該在遊戲加入時加載推薦，而不是重複調用。

示例：為用戶排名的三個“力量”物品


local MarketplaceService = game:GetService("MarketplaceService")

-- 創建要排名的產品數組
local productIdentifiers = {
    {InfoType = Enum.InfoType.GamePass, Id = 123},
    {InfoType = Enum.InfoType.Product, Id = 456},
    {InfoType = Enum.InfoType.Product, Id = 789}
}

-- 可選：將調用包裝在異步任務中，這樣如果請求較慢，則不會凍結 UI / 遊戲
task.spawn(function()
    -- 使用 pcall 以優雅地處理錯誤
    local success, result = pcall(function()
        return MarketplaceService:RankProductsAsync(productIdentifiers)
    end)

    if not success then
        -- 如果失敗，'result' 是錯誤消息。
        warn("排名產品失敗:", result)
    end

    -- 將返回的物品加載到商店中。
    for i, rankedItem in ipairs(rankedProducts) do
        local productIdentifier = rankedItem.ProductIdentifier
        local productInfo = rankedItem.ProductInfo
        -- ...
        -- 將 productInfo 添加到商店的邏輯
    end
end)

顯示您的熱門通行證

如果您的遊戲在過去 28 天內沒有銷售任何物品，則 RecommendTopProductsAsync 將返回一個空列表。必須在過去 28 天內進行至少一次購買，該 API 才能生成推薦。

RecommendTopProductsAsync 接受一個 InfoType 值數組並返回用戶最有可能參與和購買的最多 50 項物品。您可以使用此方法在您的遊戲內商店中創建“最佳推薦”部分。

如果無法確定推薦，RecommendTopProductsAsync 將返回 0 項物品。用戶已擁有的任何通行證也不會返回。

在少數情況下，對排名模型的調用可能會變慢。為了幫助防止對用戶造成延遲，我們建議使用 task.spawn 以使對 RecommendTopProducts 的調用非阻塞。

示例：遊戲內商店中的“最佳推薦”選項卡


local MarketplaceService = game:GetService("MarketplaceService")

-- 創建要包含的產品類型數組。在這種情況下，包括遊戲通行證和開發者產品
local productTypes = {Enum.InfoType.GamePass, Enum.InfoType.Product}

-- 可選：將調用包裝在異步任務中，這樣如果請求較慢，
-- 它不會凍結 UI / 遊戲
task.spawn(function()
    -- 使用 pcall 以優雅地處理錯誤
    local success, result = pcall(function()
        return MarketplaceService:RecommendTopProductsAsync(productTypes)
    end)

    if not success then
        -- 如果失敗，'result' 是錯誤消息。
        warn("排名產品失敗:", result)
    end

    -- 將返回的物品加載到商店中。 確保過濾掉任何
    -- 不符合條件的物品，例如用戶已無法再購買的開發者產品
    for i, rankedItem in ipairs(rankedProducts) do
        local productIdentifier = rankedItem.ProductIdentifier
        local productInfo = rankedItem.ProductInfo
        -- ...
        -- 將 productInfo 添加到商店的邏輯
    end
end)