العلامات (Tags)

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

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

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

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

نصيحة

قد يحتاج فريق التسويق إلى المشاركة في هذه العملية للمساعدة في تحديد العلامات التي تتوافق بشكل أفضل مع أهدافك التسويقية واستراتيجيات تقسيم الجمهور.

قيم العلامات

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

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

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

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

عوامل تشغيل العلامات (Tag operators)

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

• عوامل تشغيل علامة 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

ملاحظة

عوامل التشغيل “Not set” و “any” متاحة لجميع أنواع العلامات.

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

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

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

مثال

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

مثال: تعيين علامة خاصة بالمستخدم عبر UserID

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

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

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

الاسم	النوع	مكان التعيين	الوصف
Application Version	Version	SDK	الإصدار الحالي من التطبيق المثبت على الجهاز
Browser Type	String	SDK	عند تسجيل جهاز لمشروع الويب الخاص بك، يتم تتبع نوعه - جوال أو سطح مكتب - تلقائيًا
City	String	Server	آخر موقع جغرافي مسجل للجهاز
Country	String	Server	آخر موقع جغرافي مسجل للجهاز
Device Model	String	SDK	يشير إلى طراز الجهاز الذي تم تثبيت التطبيق عليه
First Install	Date	Server	يشير إلى الوقت الذي تم فيه تسجيل جهاز لتلقي الإشعارات لأول مرة
In-App Product	List	SDK	المنتجات داخل التطبيق التي اشتراها مستخدم التطبيق
Last In-App Purchase Date	Date	SDK	تاريخ آخر عملية شراء داخل التطبيق تمت على الجهاز
Language	String	SDK	اختصار من حرفين صغيرين للغة الجهاز وفقًا لـ ISO-639-1؛ مأخوذ من إعدادات الجهاز
Last Application Open	Date	Server	وقت آخر تشغيل للتطبيق على الجهاز
Last Email Open	Date	Server	التاريخ الذي سجل فيه عنوان البريد الإلكتروني للجهاز حدث فتح بريد إلكتروني مؤخرًا
Last Email Open Message Code	String	Server	رمز الرسالة لآخر بريد إلكتروني تم فتحه (التنسيق XXXX-XXXXXXXX-XXXXXXXX). يتم تحديثه عند كل حدث PW_EmailOpen. استخدمه لتقسيم مستلمي حملة بريد إلكتروني معينة حسب من فتحها
Last Email Click	Date	Server	التاريخ الذي سجل فيه عنوان البريد الإلكتروني للجهاز نقرة على رابط بريد إلكتروني مؤخرًا
Last Email Click Message Code	String	Server	رمز الرسالة لآخر بريد إلكتروني تم النقر على رابط فيه (التنسيق XXXX-XXXXXXXX-XXXXXXXX). يتم تحديثه عند كل حدث PW_EmailLinkClicked. استخدمه لتقسيم مستلمي حملة بريد إلكتروني معينة حسب من نقر
Last Email Confirm	Date	Server	تاريخ آخر تأكيد اشتراك Double Opt-In لعنوان البريد الإلكتروني للجهاز
Bounced Email	Date	Server	التاريخ الذي حدث فيه ارتداد قوي (hard bounce) لعنوان البريد الإلكتروني هذا. يتم تخزينه كتاريخ لتمكين التقسيم الزمني، على سبيل المثال، لاستبعاد المستخدمين الذين لديهم ارتدادات حديثة
Unsubscribed Emails	Boolean	SDK	يشير إلى ما إذا كان المستخدم قد ألغى الاشتراك في تلقي رسائل البريد الإلكتروني من تطبيقك
OS Version	Version	SDK	إصدار نظام التشغيل الذي يعمل على الجهاز
Platform	String	SDK	المنصة التي يستخدم عليها المستخدم مشروعك.
Push Alerts Enabled	Boolean	SDK	يشير إلى ما إذا كانت تنبيهات الإشعارات اللحظية مسموح بها في إعدادات الجهاز
SDK Version	Version	SDK	إصدار Pushwoosh SDK المطبق على الجهاز

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

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

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

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

addTag

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

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

جسم الطلب (Request Body)

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

200

{
    "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”

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

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

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

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

iOS Native

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

Android Native

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

التوثيق

Cordova

Cordova

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

التوثيق

Flutter

Flutter

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

التوثيق

React Native

React Native

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

التوثيق

Unity

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

Unreal Engine

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

التوثيق

Expo

Expo

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

التوثيق

.NET MAUI

.NET MAUI

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

التوثيق

Outsystems

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

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

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

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

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

نصيحة

قبل إنشاء شريحة عبر API، تحقق من القيم التي لدى المستخدمين على أجهزتهم عبر طلب /getTagStats.