Tags

تُعد العلامات (Tags) واحدة من أكثر الأدوات فائدة التي تقدمها 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

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

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

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

مثال

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

{
   "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	وقت آخر تشغيل للتطبيق على الجهاز
OS Version	Version	SDK	إصدار نظام التشغيل الذي يعمل على الجهاز
Platform	String	SDK	المنصة التي يستخدم عليها المستخدم مشروعك.
Push Alerts Enabled	Boolean	SDK	يشير إلى ما إذا كانت تنبيهات الإشعارات اللحظية مسموح بها في إعدادات الجهاز
SDK Version	Version	SDK	إصدار Pushwoosh SDK المطبق على الجهاز
Unsubscribed Emails	Boolean	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.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

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

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

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

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