العلامات

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

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

تحديد العلامات التي يجب استخدامها

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

قيم العلامات

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

أنواع العلامات

Integer — تستخدم للبيانات الصحيحة (كمية النقود المكتسبة في اللعبة، المستوى المحقق، العمر).
String — تستخدم للقيم النصية (اسم المستخدم، البريد الإلكتروني، المعرفات).
List — نفس نوع String، ولكن قد يكون لكل مستخدم قيم متعددة معينة في وقت واحد (تفضيلات الموسيقى، فئات الأخبار، تفضيلات المطبخ).
Boolean — نوع العلامة true / false.
Date — تستخدم لتواريخ التقويم. بشكل أساسي، هذا هو نوع علامة عدد صحيح يخزن طوابع زمنية Unix Epoch (يتم تحويلها تلقائيًا من/إلى التاريخ الميلادي).
Price — يسمح بتعيين القيم وفقًا للعملة المحددة بتنسيق “*.XX” اعرف المزيد.
Version — تستخدم لتحديد الإصدارات. مثال على التنسيق المسموح به هو w.x.y.z (رئيسي.ثانوي.تصحيح.بناء). القيمة القصوى لكل جزء من الإصدار هي 9999، لذا لا يمكن أن يكون رقم الإصدار الأقصى أكبر من 9999.9999.9999.9999.

عوامل العلامات

لكل نوع من أنواع العلامات مجموعة محددة من العوامل القابلة للتطبيق. تحدد عوامل العلامات العلاقة بين العلامة وقيمها لأغراض التقسيم.

عوامل علامة Integer: is, is not, are, not in, not set, any
عوامل علامة String: is, is not, are, not in, not set, any
عوامل علامة List: in, not in, not set, any
عوامل علامة Boolean: is (true/false), not set, any
عوامل علامة Date: exactly on, on or after, on or before, between, not set, any
عوامل علامة Price: is, is not, greater or equals, less or equals, between, in, not in, not set, any
عوامل علامة Version: is, is not, greater or equals, less or equals, between, in, not in, not set, any

نطاق العلامة: عام مقابل خاص بالمستخدم

عند إنشاء علامة، تختار كيفية تخزين قيمها:

عام (افتراضي، user_specific: false): يتم تخزين قيمة العلامة لكل جهاز (HWID). يمكن لكل جهاز لنفس المستخدم أن يحمل قيمة مختلفة بشكل مستقل.
خاص بالمستخدم (user_specific: true): يتم تخزين قيمة العلامة لكل مستخدم (UserID). عند تعيينها عبر UserID، يتم تطبيق القيمة على جميع أجهزة المستخدم دفعة واحدة. مفيد للسمات التي تخص الشخص، وليس جهازًا معينًا: مستوى الاشتراك، نقاط الولاء، اللغة المفضلة.

مثال

لدى المستخدم إصدارات iOS و Android من تطبيقك مثبتة. يؤدي تعيين علامة subscription_tier إلى "premium" عبر UserID الخاص به إلى تطبيقها على كلا الجهازين على الفور. مع علامة عامة، ستحتاج إلى تعيينها لكل جهاز على حدة.

{
   "request":{
      "application": "XXXXX-XXXXX",
      "userId": "the id of a specific user",
      "tags": {
           "subscription_tier": "premium",
           "loyalty_points": 350
      }
   }
}

العلامات الافتراضية

هذه العلامات متاحة من Pushwoosh بشكل افتراضي، لذا لا يتعين عليك (وفي الواقع، لا ينبغي عليك) تعيينها يدويًا. يتم تعيين معظمها من التطبيق وإرسالها إلى خادمنا عبر registerDevice ومكالمات API أخرى، وبعضها يتم تعيينه بواسطة الخادم نفسه.

الاسم	النوع	مكان التعيين	الوصف
إصدار التطبيق	Version	SDK	الإصدار الحالي من التطبيق المثبت على الجهاز
نوع المتصفح	String	SDK	عند تسجيل جهاز لمشروع الويب الخاص بك، يتم تتبع نوعه – محمول أو مكتبي – تلقائيًا
المدينة	String	الخادم	آخر موقع جغرافي مسجل للجهاز
البلد	String	الخادم	آخر موقع جغرافي مسجل للجهاز
طراز الجهاز	String	SDK	يشير إلى طراز الجهاز الذي تم تثبيت التطبيق عليه
أول تثبيت	Date	الخادم	يشير إلى الوقت الذي تم فيه تسجيل الجهاز للإشعارات لأول مرة
منتج داخل التطبيق	List	SDK	المنتجات داخل التطبيق التي اشتراها مستخدم التطبيق
تاريخ آخر شراء داخل التطبيق	Date	SDK	تاريخ آخر عملية شراء داخل التطبيق تمت على الجهاز
اللغة	String	SDK	اختصار من حرفين صغيرين للغة الجهاز وفقًا لـ ISO-639-1؛ مأخوذ من إعدادات الجهاز
آخر فتح للتطبيق	Date	الخادم	وقت آخر تشغيل للتطبيق على الجهاز
آخر فتح للبريد الإلكتروني	Date	الخادم	التاريخ الذي سجل فيه عنوان البريد الإلكتروني للجهاز حدث فتح بريد إلكتروني مؤخرًا
رمز رسالة آخر بريد إلكتروني مفتوح	String	الخادم	رمز الرسالة لآخر بريد إلكتروني تم فتحه (تنسيق `XXXX-XXXXXXXX-XXXXXXXX`). يتم تحديثه عند كل حدث `PW_EmailOpen`. استخدمه لتقسيم مستلمي حملة بريد إلكتروني معينة حسب من فتحها
آخر نقرة على البريد الإلكتروني	Date	الخادم	التاريخ الذي سجل فيه عنوان البريد الإلكتروني للجهاز نقرة على رابط بريد إلكتروني مؤخرًا
رمز رسالة آخر بريد إلكتروني تم النقر عليه	String	الخادم	رمز الرسالة لآخر بريد إلكتروني تم النقر على رابط فيه (تنسيق `XXXX-XXXXXXXX-XXXXXXXX`). يتم تحديثه عند كل حدث `PW_EmailLinkClicked`. استخدمه لتقسيم مستلمي حملة بريد إلكتروني معينة حسب من نقر
آخر تأكيد للبريد الإلكتروني	Date	الخادم	تاريخ آخر تأكيد اشتراك Double Opt-In لعنوان البريد الإلكتروني للجهاز
البريد الإلكتروني المرتد	Date	الخادم	التاريخ الذي حدث فيه ارتداد قاسي لعنوان البريد الإلكتروني هذا. يتم تخزينه كتاريخ لتمكين التقسيم الزمني، على سبيل المثال، لاستبعاد المستخدمين الذين لديهم ارتدادات حديثة
رسائل البريد الإلكتروني غير المشترك بها	Boolean	SDK	يشير إلى ما إذا كان المستخدم قد ألغى الاشتراك في تلقي رسائل البريد الإلكتروني من تطبيقك
إصدار نظام التشغيل	Version	SDK	إصدار نظام التشغيل الذي يعمل على الجهاز
المنصة	String	SDK	المنصة التي يستخدم عليها المستخدم مشروعك.
تنبيهات الإشعارات اللحظية مفعلة	Boolean	SDK	يشير إلى ما إذا كانت تنبيهات الإشعارات اللحظية مسموح بها في إعدادات الجهاز
إصدار SDK	Version	SDK	إصدار Pushwoosh SDK المطبق على الجهاز

العلامات المخصصة

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

كيفية إعداد علامة مخصصة

إنشاء علامة مسبقًا هو أمر اختياري. يؤدي إرسال اسم علامة جديد عبر setTags إلى إنشائها تلقائيًا، مع استنتاج النوع من القيمة. يصبح العدد الصحيح Integer، ويصبح الرقم الذي يحتوي على فاصلة عشرية Price، ويصبح النص String (أو Date، لتنسيق تاريخ ووقت معترف به مثل 2024-10-02 22:11)، وتصبح المصفوفة List، ويصبح المتغير المنطقي Boolean. أضف العلامة بشكل صريح أولاً، عبر لوحة التحكم أو /addTag، لعلامة Version، حيث لا يمكن للاكتشاف التلقائي استنتاجها، أو لعلامة خاصة بالمستخدم. يتم تمكين الإنشاء التلقائي للعلامات افتراضيًا لغالبية الحسابات. إذا لم تقم setTags بإنشاء علامة جديدة كما هو متوقع، فاتصل بدعم Pushwoosh للتحقق مما إذا كان قد تم إيقاف تشغيله لحسابك.

يمكنك إضافة علامة جديدة في لوحة تحكم Pushwoosh أو استخدام طريقة /addTag.

addTag

POST https://api.pushwoosh.com/json/1.3/addTag

تنشئ علامة في حسابك.

جسم الطلب

الاسم	النوع	الوصف
auth*	string	رمز الوصول إلى API من لوحة تحكم Pushwoosh.
tag*	object	معلمات العلامة.
tag.name*	string	اسم العلامة.
tag.type*	integer	نوع العلامة. انظر القيم الممكنة أدناه.
tag.user_specific	boolean	عندما تكون `true`، يتم تخزين قيمة العلامة على مستوى المستخدم ومشاركتها عبر جميع أجهزة المستخدم عند تعيينها بواسطة UserID. عندما تكون `false` (افتراضي)، تكون العلامة على مستوى الجهاز ويتم تعيينها لكل HWID.

{
    "status_code": 200,
    "status_message": "OK",
    "response": {
        "result": true
    }
}

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // مطلوب، رمز الوصول إلى API من لوحة تحكم Pushwoosh
    "tag": {
      "name": "TAG_NAME",    // مطلوب
      "type": 1,             // مطلوب، انظر القيم الممكنة أدناه
      "user_specific": false // اختياري. true = على مستوى المستخدم؛ false = على مستوى الجهاز (افتراضي)
    }
  }
}

أنواع قيم العلامات الممكنة:

1 - Integer
2 - String
3 - List
4 - Date
5 - Boolean
6 - Decimal. مثال: 19.95
7 - Version. مثال: “1.0.0.0”

كيفية جمع المعلومات من المستخدمين

بمجرد إضافة وتكوين علامة، تكون جاهزة لبدء جمع المعلومات من المستخدمين. اتبع هذه الخطوات لتنفيذها:

ادمج Pushwoosh SDK في مشروعك باتباع دليل التكامل ذي الصلة.
استخدم دالة setTags لتعيين العلامات وجمع بيانات المستخدم.

فيما يلي أمثلة تنفيذ لأطر عمل مختلفة باستخدام دالة setTags.

iOS Native

NSDictionary *tags = @{
    @"Alias" : aliasField.text,
    @"FavNumber" : @([favNumField.text intValue]),
    @"price" : [PWTags incrementalTagWithInteger:5],
    @"List" : @[ @"Item1", @"Item2", @"Item3" ]
};

[[PushNotificationManager pushManager] setTags:tags];

الوثائق

Android Native

pushwoosh.setTags(Tags.intTag("intTag", 42));

الوثائق

Cordova

PushNotification.prototype.setTags = function(  config, success, fail  )

الوثائق

Flutter

Future<void> setTags(Map tags) async {
  await _channel.invokeMethod("setTags", {"tags" : tags});
}

الوثائق

React Native

pushNotification.setTags({
    "string_tag" : "Hello world",
    "int_tag" : 42,
    "list_tag":["hello", "world"]
});

الوثائق

Unity

SetIntTag

تعيين علامة Integer للجهاز.

public virtual void SetIntTag(string tagName, int tagValue)

SetStringTag

تعيين علامة String للجهاز.

public virtual void SetStringTag(string tagName, string tagValue)

SetListTag

تعيين علامة List للجهاز.

public virtual void SetListTag(string tagName, List<object> tagValues)

الوثائق

Unreal Engine

FPushwooshModule& pushwoosh = FPushwooshModule::Get();
pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }");

الوثائق

Expo

Pushwoosh.setTags({ "key": keyValue, "value": inputValue });

الوثائق

.NET MAUI

NSDictionary *tags = @{
    @"Alias" : aliasField.text,
    @"FavNumber" : @([favNumField.text intValue]),
    @"price" : [PWTags incrementalTagWithInteger:5],
    @"List" : @[ @"Item1", @"Item2", @"Item3" ]
};
[[PushNotificationManager pushManager] setTags:tags];

الوثائق

Outsystems

معلمات الإدخال Tags – قائمة بسجلات العلامات التي تحتوي على TagName و TagValue.

يجب أن يكون TagName دائمًا من نوع Text.
يمكن أن يكون TagValue Text, Integer, Boolean, Date, إلخ.

اعرف المزيد

تعيين العلامات عبر API

بينما في معظم الحالات (99%)، يتم تعيين العلامات من التطبيق، يمكنك أيضًا تعيين العلامات عبر Pushwoosh API. فيما يلي مثال على طلب نموذجي إلى نقطة نهاية /setTags:

POST https://api.pushwoosh.com/json/1.3/setTags

{
   "request": {
      "application": "XXXXX-XXXXX", // مطلوب، رمز تطبيق Pushwoosh
      "hwid": "8f65bXXXf378eXXXbeceXXX4e153XXX2", // مطلوب، معرف الجهاز المستخدم في /registerDevice API
      "tags": { // مطلوب
           "StringTag": "string value", // مثال على علامة نصية
           "IntegerTag": 42, // مثال على علامة عدد صحيح
           "ListTag": ["string1", "string2"], // مثال على علامة قائمة
           "DateTag": "2024-10-02 22:11", // ملاحظة: يجب أن يكون الوقت بتوقيت UTC
           "BooleanTag": true // القيم الصالحة: true, false
      }
   }
}

لمزيد من التفاصيل، راجع وثائق setTags API

يتم إنشاء اسم علامة غير موجود تلقائيًا في المرة الأولى التي يرسلها setTags، مع استنتاج النوع من القيمة: يصبح العدد الصحيح Integer، ويصبح الرقم الذي يحتوي على فاصلة عشرية Price، ويصبح النص String (أو Date، لتنسيق تاريخ ووقت معترف به مثل 2024-10-02 22:11)، وتصبح المصفوفة List، ويصبح المتغير المنطقي Boolean. أنشئ علامة Version بشكل صريح أولاً، عبر لوحة التحكم أو /addTag، حيث لا يمكن للإنشاء التلقائي استنتاجها. يتم تمكين الإنشاء التلقائي للعلامات افتراضيًا لغالبية الحسابات. إذا لم تقم setTags بإنشاء علامة جديدة كما هو متوقع، فاتصل بدعم Pushwoosh للتحقق مما إذا كان قد تم إيقاف تشغيله لحسابك.

استخدام علامة المدينة الافتراضية

يتم تحديد موقع الجهاز بناءً على عنوان IP الخاص به في اللحظة التي تم فيها تشغيل تطبيقك على هذا الجهاز لآخر مرة. يقدم GeoIP بيانات الموقع إلى Pushwoosh، ويحفظ Pushwoosh الموقع المستلم من GeoIP كقيمة لعلامة المدينة (City) لجهاز معين.

في بعض الحالات، يختلف الموقع الذي يقدمه GeoIP عن اسم المدينة — على سبيل المثال، عندما يشير إلى منطقة من مدينة أو وحدة إدارية أخرى. يرجى توخي الحذر عند استخدام علامة المدينة (City) الافتراضية لأغراض التقسيم: تأكد من تحديد القيم المناسبة.

على سبيل المثال، إذا كنت ستستهدف المستخدمين من ميونيخ، فيجب عليك تغطيتها بمجموعة من قيم علامة المدينة (City)، بما في ذلك “Munich” نفسها (مع جميع القيم المقابلة، مثل المتغيرات المختلفة للهجاء التي يمكن أن يعيدها GeoIP ويتم حفظها كقيم للعلامات) والعديد من المناطق المجاورة.