경험 알림

경험 알림은 13세 이상의 옵트인 사용자들이 시기적절하고 개인화된 알림을 통해 좋아하는 게임을 계속 업데이트 받을 수 있는 방법입니다. 개발자로서, 사용자가 알아야 할 가장 중요한 게임 내 활동이 무엇인지 결정하고, 알림 내용을 정의할 수 있습니다.

경험 알림 시스템은 다음 기능을 제공합니다:

• 매개변수를 사용한 사용자 정의 알림 — 매개변수가 포함된 알림 메시지를 사용자 정의할 수 있는 완전한 유연성, 예를 들어:

  당신의 금색 거위 알이 부화했습니다!

  Allie @LaterSk8er1가 도쿄 투어 트랙에서 당신의 기록을 깨뜨렸습니다!

• 출시 데이터 — 알림 수신자가 참여할 때 Player:GetJoinData()를 통해 읽을 수 있는 선택적 출시 데이터를 포함합니다. 이는 사용자를 좌표 위치로 안내하거나 참여 경험을 개인화하는 데 사용할 수 있습니다.

• 분석 지원 — 제작자 대시보드에서 도달 가능한 청중과 알림 성과를 추적합니다.

자격 요건

알림을 보내기 위해 API를 사용하려면 게임이 다음 기본 기준을 충족해야 합니다:

• 출시 이후 최소 100회의 방문이 있어야 합니다.
• 게임이 검토 중이어서는 안 됩니다.
• 개발자인 귀하가 게임 관리 권한을 가져야 합니다.

사용 지침

구현

경험 알림을 구현하는 것은 알림 문자열 만들기와 패키지 포함하기에서 시작됩니다. 이러한 설정이 완료되면 알림 전송하기와 같은 선택적 사용자 정의 매개변수를 사용하는 알림을 보낼 수 있습니다.

또한, Open Cloud API를 사용하여 자유로운 API 요청을 통해 알림을 트리거할 수 있습니다.

알림 문자열 만들기

플레이어 초대 프롬프트와 마찬가지로, 크리에이터 대시보드에서 알림 문자열을 생성하고 편집해야 합니다. 기본 게임 알림 문자열이 없으므로 이 단계는 필수입니다.

1. 크리에이터 대시보드로 이동합니다.

2. 배지와 마찬가지로, 알림 문자열은 특정 게임에 연결됩니다. 해당 게임의 섬네일을 찾아 클릭합니다.

3. 왼쪽 열의 참여 아래에서 알림을 클릭합니다.

4. 중앙 영역에서 알림 문자열 생성 버튼을 클릭합니다.

5. 식별자 이름(당신에게만 보임)과 사용자 정의 알림 문자열을 입력합니다. 이는 99자로 제한되며 무제한 사용자 정의 매개변수를 포함할 수 있습니다. 알림은 자동으로 게임의 제목을 알림 제목으로 사용하지만, 추가로 **{experienceName}**을 사용하여 알림 본문 텍스트에서 게임을 참조할 수 있습니다.

   예시 알림 문자열:

   당신은 매주 도전을 완수하기 위해 {numQuests} 퀘스트만 남았습니다!

   당신의 {eggName}가 태어났습니다! 새로운 애완동물을 만나보세요.

   당신은 이번 주에 {numRaces} 경주에서 승리했으며, {racetrackName} 트랙의 잠금을 해제했습니다!

   {userId-friend}가 도쿄 투어 트랙에서 당신의 기록을 깨뜨렸습니다! 복수할 시간인가요?

   알림 문자열을 작성하기 전에 시스템 사용에 대한 가이드라인을 검토해 주십시오.

6. 준비가 되면 알림 문자열 생성 버튼을 클릭합니다.

7. 알림 페이지에서 알림 테이블의 작업 열에서 ⋯ 버튼을 클릭하고 자산 ID 복사를 선택합니다.

8. 복사한 ID를 예제 스크립트에서 payload 테이블의 messageId 키 값으로 사용합니다.

패키지 포함하기

경험 알림을 구현하려면 제작자 스토어에서 Luau 패키지를 얻어야 합니다.

1. Studio의 창 메뉴 또는 홈 탭 도구 모음에서 도구 상자를 열고 제작자 스토어 탭을 선택합니다.

   

2. 모델 정렬이 선택되어 있는지 확인한 후, 카테고리에 대한 모두 보기 버튼을 클릭합니다.

   

3. 패키지 타일을 찾고 클릭합니다.

4. Open Cloud 모듈을 찾고 클릭하거나 3D 보기로 드래그 앤 드롭합니다.

   

5. 탐색기 창에서 전체 OpenCloud 모델을 ServerScriptService로 이동합니다.

경험 알림 전송하기

알림 문자열 만들기와 패키지를 프로젝트에 포함하면 서버 사이드 스크립트에서 알림을 보낼 수 있습니다. 알림은 옵트인된 13세 이상의 사용자에게 로블록스 알림 스트림을 통해 전달되며, 사용자는 알림의 참여 버튼을 통해 직접 경험에 참여하고, 출시 데이터에 따라 스폰합니다.

특정 사용자에게 기본 알림을 전송하려면 페이로드의 messageId 필드에 알림 문자열 자산 ID를 포함한 다음, 수신자의 Player.UserId와 요청 데이터를 사용하여 createUserNotification 함수를 호출합니다.

경험 알림 전송하기
local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

-- 페이로드에서 "messageId"는 알림 자산 ID의 값입니다
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT"
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

매개변수를 사용하여 알림 사용자 정의하기

각 수신자에 대한 알림을 사용자 정의하려면 알림 문자열에 매개변수를 포함한 다음, API를 호출할 때 매개변수를 사용자 정의할 수 있습니다. 예를 들어 알림 문자열을 다음과 같이 정의할 수 있습니다:

그런 다음 스크립트에서 userId-friend 및 points 매개변수를 설정합니다:

매개변수를 사용하여 알림 사용자 정의하기
local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

local userIdFriendParam = {int64Value = 3702832553}
local pointsParam = {stringValue = "5"}

-- 페이로드에서 "messageId"는 알림 자산 ID의 값입니다
-- 이 예제에서 알림 문자열은 "{userId-friend}가 당신의 최고 점수를 {points}점 차로 이겼습니다! 레벨업할 시간입니다?"입니다
local userNotification = {
	payload = {
		messageId = "ef0e0790-e2e8-4441-9a32-93f3a5783bf1",
		type = "MOMENT",
		parameters = {
			["userId-friend"] = userIdFriendParam,
			["points"] = pointsParam
		}
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

사용자가 알림을 활성화하도록 권장하기

사용자가 당신의 경험에 대한 알림을 활성화하도록 권장하기 위해, 13세 이상의 사용자에게 ExperienceNotificationService:PromptOptIn() 메서드를 사용하여 경험 내에서 권한 요청 프롬프트를 표시할 수 있습니다.

프롬프트를 당연히 알림을 받을 필요가 있는 경험 내의 적절한 맥락에서 발생시킬 수 있습니다. 프롬프트 텍스트는 사용자 정의할 수 없으며 모든 경험에 대해 표준화되어 있습니다.

사용자가 다음 조건을 만족하는 경우 모달이 표시되지 않습니다:

• 13세 미만입니다.
• 이미 당신의 경험에 대해 알림을 활성화했습니다.
• 지난 30일 내에 당신의 경험에 대한 권한 요청 프롬프트를 이미 보았습니다.

사용자에게 알림을 활성화하라는 프롬프트를 표시하려면 사용자가 자격이 있는지 먼저 확인해야 합니다. 확인되면, 권한 요청 프롬프트를 사용자에게 표시할 수 있습니다.

1. pcall()으로 감싸서 비동기 네트워크 호출이 실패할 수 있으므로 ExperienceNotificationService:CanPromptOptInAsync()를 호출합니다.
2. 사용자가 프롬프트할 수 있는 경우 ExperienceNotificationService:PromptOptIn()을 호출합니다.

로컬 스크립트 - 알림 권한 프롬프트 구현
local ExperienceNotificationService = game:GetService("ExperienceNotificationService")

-- 사용자가 알림 활성화를 위한 프롬프트를 받을 수 있는지 확인하는 함수
local function canPromptOptIn()
	local success, canPrompt = pcall(function()
		return ExperienceNotificationService:CanPromptOptInAsync()
	end)
	return success and canPrompt
end

local canPrompt = canPromptOptIn()
if canPrompt then
	local success, errorMessage = pcall(function()
		ExperienceNotificationService:PromptOptIn()
	end)
end

-- 옵트인 프롬프트 닫힘 이벤트 수신
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("옵트인 프롬프트가 닫혔습니다")
end)

출시 및 분석 데이터 포함하기

사용자 경험을 더욱 개선하기 위해 알림에 출시 데이터를 포함할 수 있으며, 이는 사용자를 좌표 위치로 안내하거나 참여 경험을 개인화하는 데 유용합니다. 또한, 클릭 수 분석 등 분석 데이터를 포함할 수 있어 다양한 카테고리의 알림 성과를 구분하는 데 도움이 됩니다. 출시 데이터가 설정되고 사용되는 방법에 대한 예는 플레이어 초대 프롬프트 예제를 참조하세요.

출시 데이터 및 분석 데이터 포함하기
local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

-- 페이로드에서 "messageId"는 알림 자산 ID의 값입니다
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT",
		joinExperience = {
			launchData = "Test_Launch_Data"
		},
		analyticsData = {
			category = "Test_Analytics_Category"
		}
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

전송 시스템

스팸 방지 시스템이 존재하여 사용자에게 알림의 품질을 보장하고 모든 개발자를 위한 공유 알림 채널을 보호합니다. 이로 인해 알림의 전달이 보장되지 않습니다. 이 스팸 방지 시스템은 사용자 참여에 의해 직접적으로 영향을 받습니다: 사용자가 귀하의 알림에 더 많이 참여할수록 더 많은 도달 범위를 얻게 됩니다. 분석 대시보드에서 참여 메트릭을 투명하게 추적할 수 있으며, 아래에 설명되어 있습니다.

체험 알림은 고정된 스로틀 한도가 있습니다. 각 사용자는 특정 체험에서 하루에 하나의 알림만 받을 수 있으며, 사용자의 스로틀 한도에 도달했을 때 투명한 피드백을 받습니다.

또한, 다음 목록은 알림 비전달을 초래할 수 있는 몇 가지 특별한 사례를 설명합니다:

• 체험 자격 요건이 충족되지 않습니다.
• 수신자가 귀하의 체험에서 알림을 수신하도록 선택하지 않았습니다.
• 수신자의 귀하의 체험에 대한 스로틀 한도에 도달했습니다.
• 수신자의 일일 집계 스로틀 한도에 도달했습니다.
• 요청 매개변수가 누락되거나 잘못되었습니다.
• 알림 문자열이 조정되었습니다.
• 사용자 언급이 있는 알림의 경우, 다음 조건 중 하나라도 충족되면 비전달이 발생합니다:

  • 수신자와 언급된 사용자가 친구가 아닙니다.
  • 언급된 사용자가 Roblox 계정 설정의 개인정보 → 기타 설정에서 "내 활동에 대해 친구들에게 업데이트?"에 대해 아니오를 선택했습니다.

분석

Performance of your notifications and notifiable audience are displayed in the Analytics tab of the Notifications page where you configure notification strings (simply tab from Creations to Analytics).

1. Navigate to the Creator Dashboard.
2. Similar to badges, notification strings are tied to a specific game. Locate that game's thumbnail and click on it.
3. In the left column, under Engagement, click Notifications.
4. On the target page, click the Analytics tab to switch to the analytics dashboard.

알림 요약

요약 섹션은 알림의 집계 성능에 대한 스냅샷 역할을 합니다. 성능 통계를 표시하려면 최소 100개의 집계 노출이 필요합니다.

항목화된 통계

The Experience Notifications table displays detailed performance statistics for each notification with at least 100 impressions, ordered by the date of first impression for that notification.

The Name column is the key identifier for the notification. By default, the name matches the identifier name you specified when creating the notification string, but you can override it through the category field in your API calls, in which case category overrides the name. Changing the string name in the Creator Dashboard or changing the string your message ID references in the API call will generate a new row in the table.

If you'd like to A/B test the performance of different strings, it's recommended that you create an entirely new notification string with a similar name, for example:

• EggHatchA — "당신의 금색 알이 부화했습니다! 새로운 애완동물을 만나러 오세요."
• EggHatchB — "부화할 시간입니다! 새로운 애완동물을 만나러 오세요."

API 참조

함수

createUserNotification

서버 사이드 스크립트에서 알림을 전송합니다. 수신자의 Player.UserId와 UserNotification이 필요합니다. UserNotificationResult을 반환합니다.

경험 알림 전송하기
local ServerScriptService = game:GetService("ServerScriptService")

local OCUserNotification = require(ServerScriptService.OpenCloud.V2.UserNotification)
local recipientPlayerID = 505306092

-- 페이로드에서 "messageId"는 알림 자산 ID의 값입니다
local userNotification = {
	payload = {
		messageId = "5dd7024b-68e3-ac4d-8232-4217f86ca244",
		type = "MOMENT"
	}
}

local result = OCUserNotification.createUserNotification(recipientPlayerID, userNotification)

if result.statusCode ~= 200 then
	print(result.statusCode)
	print(result.error.code)
	print(result.error.message)
end

유형

UserNotification

사용자에게 전송될 알림에 대한 세부 정보를 포함하는 테이블입니다. 필수 messageId 및 type 문자열이 포함된 payload 테이블과 선택적 parameters, joinExperience, analyticsData 테이블을 포함해야 합니다.

UserNotificationResult

전송된 알림의 응답을 보유하는 래퍼 객체입니다. 다음 키-값 쌍을 포함합니다: