通行证 | 文档 - 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语句替换为用于显示通行证的UI代码
  	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将返回一个空列表。此API需要在过去28天内至少有一笔购买才能生成推荐。

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

    -- 将返回的物品加载到商店中。确保从topRankedItems中过滤掉所有不合格的物品
    -- 例如用户不能再购买的开发者产品
    for i, rankedItem in ipairs(rankedProducts) do
        local productIdentifier = rankedItem.ProductIdentifier
        local productInfo = rankedItem.ProductInfo
        -- ...
        -- 将productInfo添加到商店的逻辑
    end
end)