玩家邀请提示

除了常见的 推广 方法来增加你的玩家基础外，你可以在游戏中直接实施 邀请提示，鼓励玩家邀请他们的朋友并增加共同体验的游戏性。

邀请提示系统具有以下特点：

• 动态受邀者 — 提示玩家从选择列表中邀请多个朋友，或邀请一个特定的朋友。
• 启动数据 — 包含可选的 启动数据，在受邀朋友加入时可以通过 Player:GetJoinData() 读取。示例用例包括将被邀请的朋友引导至特定坐标位置或为受邀者个性化加入的游戏。
• 可自定义文本 — 自定义 邀请提示 消息和 通知 消息。例如，玩家的邀请提示可以写为“请你的朋友加入冒险！”，而被邀请的朋友的通知消息可以写为“{displayName} 想要你加入他们在 {experienceName} 的冒险！”。

你还可以使用 朋友邀请奖励系统 跟踪和奖励邀请者和被邀请者。

设置邀请选项

默认情况下，玩家的邀请提示显示他们朋友的菜单，并带有 邀请 按钮。要自定义提示消息、目标特定朋友或在邀请中包含启动数据，你需要设置一个 ExperienceInviteOptions 对象，包含所需的属性。

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

local player = Players.LocalPlayer

-- 构造带有自定义提示消息的邀请选项
local inviteOptions = Instance.new("ExperienceInviteOptions")
inviteOptions.PromptMessage = "请你的朋友加入冒险！"

设置通知选项

默认情况下，被朋友接收到的邀请通知包含发送者的 DisplayName、用户名和游戏名称。要自定义消息，你可以在 创作者仪表板 上创建一个 通知 资产，并将其资产 ID 包含为 ExperienceInviteOptions 的参数。

1. 访问 创作者仪表板。

2. 类似于 徽章，通知字符串与 特定游戏 相关联。找到该游戏的缩略图并单击它。

3. 在左侧栏中，点击 参与度 下的 通知。

4. 在中心区域，点击 创建通知字符串 按钮。

5. 填写一个标识符名称（仅对你可见）和自定义通知文本。请注意，必须包含 {experienceName} 作为占位符，以便为被邀请的朋友识别游戏的名称，你还可以选择通过 {displayName} 占位符包含发送者的 DisplayName。

   示例通知字符串：

   • {displayName} 想要你加入他们在 {experienceName} 的冒险！
   • {displayName} 刚刚完成了 {experienceName} 的第六阶段。你能做到吗？

6. 准备好后，点击 创建通知字符串 按钮。

7. 在通知页面的通知表格中，单击 ⋯ 按钮在 操作 列中并选择 复制资产 ID。

8. 在邀请提示的 ExperienceInviteOptions 对象中，将资产 ID 粘贴为 InviteMessageId 属性的值。

   LocalScript - 邀请多个朋友

   local SocialService = game:GetService("SocialService")
   local Players = game:GetService("Players")
   
   local player = Players.LocalPlayer
   
   -- 构造带有朋友的用户 ID 的邀请选项
   local inviteOptions = Instance.new("ExperienceInviteOptions")
   inviteOptions.InviteMessageId = "ef0e0790-e2e8-4441-9a32-93f3a5783bf1"

提示邀请

要提示邀请，首先应确定玩家 是否可以 发送邀请，因为能力可能因平台或玩家而异。一旦确认，你可以向玩家显示邀请提示。

1. 调用 SocialService:CanSendGameInviteAsync()，通过 pcall() 包裹它，因为这是一个异步网络调用，可能会偶尔失败。
2. 如果确认可以邀请，请调用 SocialService:PromptGameInvite()，第二个参数为可选的 邀请选项对象。

一旦提示，玩家将看到一个屏幕提示，邀请多个朋友，或在 邀请选项对象 中定义的特定朋友。当玩家点击一个或多个朋友的 邀请 按钮时，那些朋友将接收到包含发送者的 DisplayName、用户名和体验名称的通知。有关自定义通知的更多信息，请参见 设置通知选项。

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

local player = Players.LocalPlayer

-- 检查玩家是否可以发送邀请的函数
local function canSendGameInvite(sendingPlayer)
	local success, canSend = pcall(function()
		return SocialService:CanSendGameInviteAsync(sendingPlayer)
	end)
	return success and canSend
end

local canInvite = canSendGameInvite(player)
if canInvite then
	SocialService:PromptGameInvite(player)
end

包含启动数据

为了进一步改善体验内的合作或激励玩家邀请，你可以在邀请提示中包含 启动数据，这在将邀请的朋友引导到坐标位置或为受邀者个性化加入的游戏等场景中非常有用。

1. 当 提示邀请 时，包含一个 ExperienceInviteOptions 对象，其中包含将在朋友加入游戏时使用的相关数据，例如发送者的 Player.UserId、在加入时授予朋友的 徽章 的 ID 或用于生成朋友的坐标位置。如果你需要汇编多个数据项，请使用 JSONEncode() 对数据进行编码。

   多个朋友特定朋友

   LocalScript - 邀请多个朋友

   local HttpService = game:GetService("HttpService")
   local SocialService = game:GetService("SocialService")
   local Players = game:GetService("Players")
   
   local player = Players.LocalPlayer
   
   local data = {
   	senderUserID = player.UserId,
   	spawnLocation = {12, 48, 205.5}
   }
   
   local launchData = HttpService:JSONEncode(data)
   
   -- 构造带有启动数据的邀请选项
   local inviteOptions = Instance.new("ExperienceInviteOptions")
   inviteOptions.LaunchData = launchData
   
   -- 检查玩家是否可以发送邀请的函数
   local function canSendGameInvite(sendingPlayer)
   	local success, canSend = pcall(function()
   		return SocialService:CanSendGameInviteAsync(sendingPlayer)
   	end)
   	return success and canSend
   end
   
   local canInvite = canSendGameInvite(player)
   if canInvite then
   	SocialService:PromptGameInvite(player, inviteOptions)
   end

   请始终记得将包含启动数据的 inviteOptions（最大 200 个字符）作为第二个参数传递给 PromptGameInvite()。

2. 对于通过通知加入的朋友，服务器端需要检查启动数据，使用 Player:GetJoinData()。如果你在邀请提示中将多个数据项编码为 JSON，请记得使用 JSONDecode() 对其进行解码。

   Script - 使用邀请启动数据

   local HttpService = game:GetService("HttpService")
   local Players = game:GetService("Players")
   
   local ATTEMPT_LIMIT = 10
   local RETRY_DELAY = 1
   
   local function onPlayerAdded(player)
   	local launchData
   
   	for _ = 1, ATTEMPT_LIMIT do
   		task.wait(RETRY_DELAY)
   		local joinData = player:GetJoinData()
   		if joinData.LaunchData ~= "" then
   			launchData = joinData.LaunchData
   			break
   		end
   	end
   
   	if launchData then
   		local data = HttpService:JSONDecode(launchData)
   		print(data.senderUserID)
   		print(data.spawnLocation)
   	else
   		warn("未收到启动数据！")
   	end
   end
   
   Players.PlayerAdded:Connect(onPlayerAdded)

   启动数据在朋友通过邀请加入后可能需要几秒钟才会出现。如上面的代码示例所示，建议等待启动数据到达后再尝试使用它。

3. 如果启动数据存在，你可以将其用于各种设计场景，包括：

   • 将即将到来的朋友生成到发送者刚完成的具有挑战性的障碍课程的起点，基于通过启动数据传递的坐标位置。
   • 基于启动数据中的 Player.UserId 检查 发送者 是否在该地点，并将朋友的角色传送到发送者的角色附近。