إشعارات التجربة

إشعارات التجربة هي وسيلة للمستخدمين الذين ينضمون الذين تبلغ أعمارهم 13 عاماً وأكبر للبقاء على اطلاع بألعابهم المفضلة من خلال إشعارات مخصصة في الوقت المناسب. بصفتك المطور، يمكنك تحديد أنواع الأنشطة داخل اللعبة التي تعتبرها الأكثر أهمية لإخطار مستخدميك عنها، بالإضافة إلى تحديد محتوى الإشعار.

يتميز نظام إشعارات التجربة بـ:

• إشعارات قابلة للتخصيص مع معلمات — مرونة كاملة لتخصيص رسالة الإشعار باستخدام معلمات، على سبيل المثال:

  لقد فقس بيضتك الذهبية!

  ألي @LaterSk8er1 قد حازت على رقمك القياسي على مسار جولة طوكيو!

• بيانات الإطلاق — ادراج بيانات الإطلاق اختيارية يمكن قراءتها من خلال Player:GetJoinData() عندما ينضم متلقي الإشعار. يمكن أن يتضمن ذلك توجيه المستخدم إلى موقع إحداثي أو تخصيص تجربته عند الانضمام.

• دعم التحليلات — تتبع جمهورك القابل للوصول وأداء إشعاراتك في لوحة تحكم المبدعين.

متطلبات الأهلية

In order to use the APIs to send notifications, the game must meet the following base criteria:

• الحد الأدنى 100 زيارة منذ الإطلاق.
• يجب أن لا تكون اللعبة تحت الإشراف.
• يجب أن يكون لديك كالمطور إذن لإدارة اللعبة.

إرشادات الاستخدام

التنفيذ

تبدأ عملية تنفيذ إشعارات التجربة بـ إنشاء نص إشعار وإدراج الحزمة في مشروعك. بمجرد إعداد هذه الأمور، يمكنك إرسال الإشعارات مع معلمات مخصصة اختيارية.

بدلاً من ذلك، يمكنك استخدام واجهة برمجة التطبيقات السحابية المفتوحة لتشغيل الإشعارات من خلال طلبات HTTP حرة.

إنشاء نص إشعار

As with Player Invite Prompts, you must create and edit your notification strings in the Creator Dashboard. هناك نص إعلام افتراضي للعبة، لذا هذه الخطوة مطلوبة.

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. In the center region, click the Create a Notification String button.

5. Fill in an identifier name (only visible to you) and the custom notification string; this is limited to 99 characters and can include unlimited custom parameters. Notifications will automatically use the title of your game as the notification title, but you can additionally use {experienceName} to reference your game in the notification body text.

   Example notification strings:

   أنت {numQuests} مهام بعيدة عن إكمال التحدي الأسبوعي!

   لقد فقست {eggName} الخاصة بك! تعال لتقابل حيوانك الأليف الجديد.

   لقد فزت {numRaces} سباقات هذا الأسبوع وفتحت حلبة {racetrackName}!

   {userId-friend} قد حطم سجلك على حلبة طوكيو تور! حان وقت الانتقام؟

   Before writing notification strings, please review the guidelines for using the system.

6. When ready, click the Create Notification String button.

7. On the notifications page, in the table of notifications, click the ⋯ button in the Actions column and select Copy Asset ID.

8. Use the copied ID for the messageId key value in the payload table as demonstrated in the example script.

إدراج الحزمة

لتنفيذ إشعارات التجربة، يجب عليك الحصول على حزمة Luau من متجر المبدعين.

1. من قائمة Window في الاستوديو أو شريط أدوات علامة Home، افتح Toolbox واختر علامة متجر المبدعين.

   

2. تأكد من اختيار ترتيب النماذج، ثم انقر فوق زر عرض الكل لفئة الفئات.

   

3. حدد موقع وانقر على البلاط الحزم.

4. ابحث عن وحدة Open Cloud وانقر عليها، أو اسحبها وأفلتها في العرض ثلاثي الأبعاد.

   

5. في نافذة Explorer، انقل النموذج بالكامل OpenCloud إلى ServerScriptService.

إرسال إشعار للتجربة

بمجرد إنشاء نص إشعار وإدراج الحزمة في مشروعك، يمكنك إرسال إشعارات من نصوص الخادم. سيتم تسليم الإشعارات إلى المستخدمين الذين اختاروا الانضمام (https://en.help.roblox.com/hc/en-us/articles/24769602332692-Out-of-Experience-Notifications) الذين تبلغ أعمارهم 13 عامًا أو أكثر عبر سلسلة إشعارات روبلوكس، وفي تلك المرحلة يمكنهم الانضمام إلى التجربة مباشرة عبر زر الانضمام في الإشعار والتولد وفقًا لـ بيانات الإطلاق الخاصة بك.

لإرسال إشعار أساسي إلى مستخدم معين، قم بإدراج معرف الأصل نص الإشعار في حقل messageId لحمولة الإشعار، ثم استدعِ دالة createUserNotification باستخدام Player.UserId لمتلقي الإشعار وبيانات الطلب.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- في الحمولة، "messageId" هو قيمة معرف الأصل للإشعار
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

تخصيص الإشعارات باستخدام المعلمات

لتخصيص الإشعار لكل متلقي، يمكنك إدراج المعلمات في نص الإشعار، ثم تخصيص المعلمات عند استدعاء واجهة برمجة التطبيقات. على سبيل المثال، يمكنك تعريف نص الإشعار على النحو التالي:

ثم، قم بتعيين المعلمات 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" هو قيمة معرف الأصل للإشعار
-- في هذا المثال، نص الإشعار هو "{userId-friend} beat your high score by {points} points! Time to level up?"
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. استدعِ ExperienceNotificationService:CanPromptOptInAsync(), مغلفًا في pcall() لأنه مكالمة شبكة غير متزامنة قد تفشل في بعض الأحيان.
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

-- الاستماع لحدث إغلاق مطالبة opt-in
ExperienceNotificationService.OptInPromptClosed:Connect(function()
	print("تم إغلاق مطالبة opt-in")
end)

إدراج بيانات الإطلاق والتحليلات

لتحسين تجربة المستخدم، يمكنك إدراج بيانات الإطلاق في الإشعار، والتي تكون مفيدة في سيناريوهات مثل توجيه المستخدمين إلى موقع إحداثي أو تخصيص تجربة الانضمام. بالإضافة إلى ذلك، يمكنك إدراج بيانات التحليلات لتقسيم أداء فئات مختلفة من الإشعارات. يرجى الرجوع أيضًا إلى مطالبات دعوة اللاعبين مثال على كيفية ضبط واستخدام بيانات الإطلاق.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- في الحمولة، "messageId" هو قيمة معرف الأصل للإشعار
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 ظهور إجمالي.

إحصائيات مفصلة

جدول إشعارات الخبرة يعرض إحصائيات الأداء المفصلة لكل إشعار يحتوي على 100 ظهور على الأقل، مرتبة حسب تاريخ أول ظهور لذلك الإشعار.

عمود الاسم هو المُعرّف الرئيسي للإشعار. بشكل افتراضي، يتطابق الاسم مع اسم المُعرّف الذي حددته عند إنشاء سلسلة الإشعار، ولكن يمكنك تجاوز ذلك من خلال حقل category في استدعاءات API الخاصة بك، وفي هذه الحالة، يتجاوز category الاسم. تغيير اسم السلسلة في لوحة معلومات المنشئ أو تغيير السلسلة التي يشير إليها معرف رسالتك في استدعاء API سيؤدي إلى إنشاء صف جديد في الجدول.

إذا كنت ترغب في اختبار A/B لأداء سلاسل مختلفة، يُوصى بإنشاء سلسلة إشعار جديدة تمامًا باسم مشابه، على سبيل المثال:

• EggHatchA — "لقد فقست بيضتك الذهبية! تعال لمقابلة حيوانك الأليف الجديد."
• EggHatchB — "حان وقت الفقس! تعال لمقابلة حيوانك الأليف الجديد."

مرجع واجهة برمجة التطبيقات

الدوال

createUserNotification

يرسل إشعارًا من نص خادم. يتطلب Player.UserId لمتلقي الإشعار و UserNotification. ويعيد UserNotificationResult.

local ServerScriptService = game:GetService("ServerScriptService")

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

-- في الحمولة، "messageId" هو قيمة معرف الأصل للإشعار
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

جدول يحتوي على تفاصيل حول الإشعار الذي سيتم إرساله إلى المستخدم. يجب أن يحتوي على جدول payload يحتوي على سلاسل messageId و type المطلوبة، وجداول parameters و joinExperience و analyticsData الاختيارية.

UserNotificationResult

كائن تغليف يحتفظ برد الإشعار المرسل. يحتوي على أزواج المفاتيح والقيم التالية: