العلامات (Tags)

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

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

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

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

نصيحة

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

قيم العلامات

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

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

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

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

ملاحظة

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

علامات خاصة بالتطبيق / غير خاصة بالتطبيق

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

مثال

لنفترض أن لديك تطبيقين، تطبيق أخبار ولعبة، وتريد استهداف المستخدمين الذين وافقوا صراحة على تلقي الإشعارات منك فقط. لذلك، تقوم بإنشاء علامة منطقية تسمى “Subscribed” وتعيين قيمة "true" للمستخدمين الذين يرغبون في تلقي الإشعارات منك، و "false" لأولئك الذين لا يرغبون في تلقي الإشعارات.

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

إذا كانت علامة “Subscribed” خاصة بالتطبيق، فسيتم كل شيء كما هو مخطط له. ومع ذلك، في حالة كانت هذه العلامة غير خاصة بالتطبيق، فسيقوم كل تطبيق من تطبيقاتك بالكتابة فوق القيمة التي حددها التطبيق الآخر، مما قد يفسد استهدافك ويسبب الإحباط.

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

علامات خاصة بالمستخدم

جميع العلامات في Pushwoosh خاصة بالمستخدم حسب التصميم ويتم تعيينها لجميع أجهزة المستخدم عند تعيينها بواسطة UserID بدلاً من HWID.

مثال

{
   "request":{
      "application": "XXXXX-XXXXX", // رمز تطبيق Pushwoosh
      "userId": "the id of a specific user",
      "tags": {
           "UserSpecificStringTag": "string value",
           "UserSpecificIntegerTag": 42
      }
   }
}

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

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

الاسم	النوع	مكان التعيين	الوصف
Application Version	إصدار	SDK	الإصدار الحالي من التطبيق المثبت على الجهاز
Browser Type	نص	SDK	عند تسجيل جهاز لمشروع الويب الخاص بك، يتم تتبع نوعه - محمول أو سطح مكتب - تلقائيًا
City	نص	الخادم	أحدث موقع جغرافي مسجل للجهاز
Country	نص	الخادم	أحدث موقع جغرافي مسجل للجهاز
Device Model	نص	SDK	يشير إلى طراز الجهاز الذي تم تثبيت التطبيق عليه
First Install	تاريخ	الخادم	يشير إلى الوقت الذي تم فيه تسجيل الجهاز لتلقي الإشعارات لأول مرة
In-App Product	قائمة	SDK	المنتجات داخل التطبيق التي اشتراها مستخدم التطبيق
Last In-App Purchase Date	تاريخ	SDK	تاريخ آخر عملية شراء داخل التطبيق تمت على الجهاز
Language	نص	SDK	اختصار من حرفين صغيرين للغة الجهاز وفقًا لـ ISO-639-1؛ مأخوذ من إعدادات الجهاز
Last Application Open	تاريخ	الخادم	وقت آخر تشغيل للتطبيق على الجهاز
OS Version	إصدار	SDK	إصدار نظام التشغيل الذي يعمل على الجهاز
Platform	نص	SDK	المنصة التي يستخدم عليها المستخدم مشروعك.
Push Alerts Enabled	منطقي	SDK	يشير إلى ما إذا كانت تنبيهات الإشعارات مسموح بها في إعدادات الجهاز
SDK Version	إصدار	SDK	إصدار Pushwoosh SDK المطبق على الجهاز
Unsubscribed Emails	منطقي	SDK	يشير إلى ما إذا كان المستخدم قد ألغى الاشتراك في تلقي رسائل البريد الإلكتروني من تطبيقك

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

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

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

يمكنك إضافة علامة جديدة في لوحة تحكم 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.application_specific	boolean	يحدد ما إذا كانت قيمة العلامة يجب أن تكون مختلفة لتطبيقات متعددة أو أن تكون هي نفسها عبر تطبيقات متعددة.

200

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

مثال

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // required, API access token from Pushwoosh Control Panel
    "tag": {
      "name": "TAG_NAME", // required
      "type": 1, // required, see possible values below
      "application_specific": true, // or 'false', optional. Defines whether the tag value should be different for multiple apps or be the same across multiple apps
      "user_specific": true // or 'false', optional, used for application_specific tags
    }
  }
}

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

• 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", // required, Pushwoosh application code
      "hwid": "8f65bXXXf378eXXXbeceXXX4e153XXX2", // required, hardware device ID used in /registerDevice API
      "tags": { // required
           "StringTag": "string value", // Example of a string tag
           "IntegerTag": 42, // Example of an integer tag
           "ListTag": ["string1", "string2"], // Example of a list tag
           "DateTag": "2024-10-02 22:11", // Note: time must be in UTC
           "BooleanTag": true // Valid values: true, false
      }
   }
}

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

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

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

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

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

نصيحة

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