العلامات

تُعد العلامات (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.

عوامل تشغيل العلامات

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

• عوامل تشغيل علامة 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 application code
      "userId": "the id of a specific user",
      "tags": {
           "UserSpecificStringTag": "string value",
           "UserSpecificIntegerTag": 42
      }
   }
}

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

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

الاسم	النوع	مكان التعيين	الوصف
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.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. فيما يلي مثال على طلب نموذجي إلى نقطة النهاية /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

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

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

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

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

نصيحة

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