# العلامات (Tags) تُعد العلامات (Tags) واحدة من أكثر الأدوات فائدة التي تقدمها Pushwoosh، حيث تتيح مجموعة من الوظائف المتقدمة. باستخدام العلامات، يمكنك تقسيم جمهورك وإرسال إشعارات لحظية مستهدفة لمستخدمين محددين بناءً على سماتهم. يمكن أن تحتوي العلامات على أي بيانات عشوائية مرتبطة بمستخدم أو جهاز معين. قد تتضمن هذه البيانات أسماء المستخدمين، أو المعرفات، أو المدن، أو فرق كرة القدم المفضلة، أو فئات الأخبار المفضلة، أو أي معلومات أخرى ذات صلة بمستخدميك. ## تحديد العلامات التي سيتم استخدامها ابدأ بتحديد احتياجات عملك وتحديد الطريقة التي تريد بها تقسيم جمهورك. ضع في اعتبارك عوامل مثل العمر، والموقع، وسجل الشراء داخل التطبيق، أو أي معايير أخرى ذات صلة لاستهداف المستخدمين. ## قيم العلامات يمكن أن تساعدك قيم العلامات في جعل حملات الإشعارات اللحظية أكثر ذكاءً. كل علامة قادرة على تخزين _عدد غير محدود تقريبًا من القيم_. بشكل أساسي، هذا يعني أن علامة واحدة ستكون كافية لتسجيل نوع معين من المعلومات حول كل مستخدم نهائي في قاعدة بياناتك. لا يتوفر سوى عدد قليل من العلامات لكل حساب، ولكن بالنظر إلى المساحة شبه اللانهائية لكل علامة، فإن علامتين فقط تكفيان لجمع كمية هائلة من المعلومات حول المستخدمين وإعداد أنماط استهداف معقدة للغاية. ## أنواع العلامات * **Integer (عدد صحيح)** — تُستخدم للبيانات العددية الصحيحة (كمية النقود المكتسبة في اللعبة، المستوى الذي تم الوصول إليه، العمر). * **String (نص)** — تُستخدم للقيم النصية (اسم المستخدم، البريد الإلكتروني، المعرفات). * **List (قائمة)** — مثل نوع String، ولكن قد يكون لكل مستخدم قيم متعددة معينة في وقت واحد (تفضيلات الموسيقى، فئات الأخبار، تفضيلات المطبخ). * **Boolean (منطقي)** — نوع علامة true / false. * **Date (تاريخ)** — تُستخدم لتواريخ التقويم. بشكل أساسي، هذا نوع علامة عدد صحيح يخزن طوابع زمنية Unix Epoch (يتم تحويلها تلقائيًا من/إلى التاريخ الميلادي). * **Price (سعر)** — يسمح بتعيين القيم وفقًا للعملة المحددة بتنسيق "\*.XX" [اعرف المزيد](https://en.wikipedia.org/wiki/ISO_4217). * **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` ## نطاق العلامة: عام مقابل خاص بالمستخدم عند إنشاء علامة، يمكنك اختيار كيفية تخزين قيمها: - **General (عام)** (الافتراضي، `user_specific: false`): يتم تخزين قيمة العلامة لكل جهاز (HWID). يمكن لكل جهاز لنفس المستخدم أن يحمل قيمة مختلفة بشكل مستقل. - **User-specific (خاص بالمستخدم)** (`user_specific: true`): يتم تخزين قيمة العلامة لكل مستخدم (UserID). عند تعيينها عبر UserID، يتم تطبيق القيمة على جميع أجهزة المستخدم دفعة واحدة. مفيد للسمات التي تخص الشخص، وليس جهازًا معينًا: فئة الاشتراك، نقاط الولاء، اللغة المفضلة. ### مثال لدى مستخدم إصدارات iOS و Android من تطبيقك مثبتة. يؤدي تعيين علامة `subscription_tier` إلى `"premium"` عبر UserID الخاص به إلى تطبيقها على كلا الجهازين على الفور. باستخدام علامة عامة، ستحتاج إلى تعيينها لكل جهاز على حدة. ```javascript title="مثال: تعيين علامة خاصة بالمستخدم عبر UserID" { "request":{ "application": "XXXXX-XXXXX", "userId": "the id of a specific user", "tags": { "subscription_tier": "premium", "loyalty_points": 350 } } } ``` ## العلامات الافتراضية هذه العلامات متاحة من Pushwoosh بشكل افتراضي، لذلك لا يتعين عليك (وفي الواقع، لا ينبغي عليك) تعيينها يدويًا. يتم تعيين معظمها من التطبيق وإرسالها إلى خادمنا عبر [`registerDevice`](/ar/developer/api-reference/device-api/) ومكالمات 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 | [رمز الرسالة](/ar/developer/api-reference/api-identifiers#message-code) لآخر بريد إلكتروني تم فتحه (التنسيق `XXXX-XXXXXXXX-XXXXXXXX`). يتم تحديثه عند كل حدث [`PW_EmailOpen`](/ar/product/audience-data-and-segmentation/events/default-events/#pw_emailopen). استخدمه لتقسيم مستلمي حملة بريد إلكتروني معينة حسب من فتحها | | Last Email Click | Date | Server | التاريخ الذي سجل فيه عنوان البريد الإلكتروني للجهاز نقرة على رابط بريد إلكتروني مؤخرًا | | Last Email Click Message Code | String | Server | [رمز الرسالة](/ar/developer/api-reference/api-identifiers#message-code) لآخر بريد إلكتروني تم النقر على رابط فيه (التنسيق `XXXX-XXXXXXXX-XXXXXXXX`). يتم تحديثه عند كل حدث [`PW_EmailLinkClicked`](/ar/product/audience-data-and-segmentation/events/default-events/#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](/ar/product/audience-data-and-segmentation/user-data-tags/tags) أو استخدام طريقة [`/addTag`](/ar/developer/api-reference/tags#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. | ```javascript { "status_code": 200, "status_message": "OK", "response": { "result": true } } ``` ```javascript title="مثال" { "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](/ar/developer/pushwoosh-sdk/pushwoosh-sdk-overview/) في مشروعك باتباع دليل التكامل ذي الصلة. 2. استخدم دالة [`setTags`](/ar/developer/api-reference/device-api/#settags) لتعيين العلامات وجمع بيانات المستخدم. فيما يلي أمثلة تنفيذ لأطر عمل مختلفة باستخدام دالة [`setTags`](/ar/developer/api-reference/device-api/#settags). ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [التوثيق](https://pushwoosh.github.io/pushwoosh-ios-sdk/PushwooshiOS/documentation/pushwooshframework/pushwoosh/settags(_:)/) ```java pushwoosh.setTags(Tags.intTag("intTag", 42)); ``` [التوثيق](https://pushwoosh.github.io/pushwoosh-android-sdk/pushwoosh/com.pushwoosh/-pushwoosh/set-tags.html) ``` PushNotification.prototype.setTags = function( config, success, fail ) ``` [التوثيق](/ar/developer/pushwoosh-sdk/cross-platform-frameworks/cordova/cordova-plugin-api-reference/#settags) ```dart Future setTags(Map tags) async { await _channel.invokeMethod("setTags", {"tags" : tags}); } ``` [التوثيق](https://pub.dev/documentation/pushwoosh_flutter/latest/pushwoosh_flutter/Pushwoosh/setTags.html) ```javascript pushNotification.setTags({ "string_tag" : "Hello world", "int_tag" : 42, "list_tag":["hello", "world"] }); ``` [التوثيق](https://github.com/Pushwoosh/pushwoosh-react-native-plugin/blob/master/docs/README.md#settags) ##### **SetIntTag** يعين علامة Integer للجهاز. ```csharp public virtual void SetIntTag(string tagName, int tagValue) ``` ##### **SetStringTag** يعين علامة String للجهاز. ```csharp public virtual void SetStringTag(string tagName, string tagValue) ``` ##### **SetListTag** يعين علامة List للجهاز. ```csharp public virtual void SetListTag(string tagName, List tagValues) ``` [التوثيق](https://github.com/Pushwoosh/pushwoosh-unity/blob/master/Documentation/README.md#pushwoosh) ```cpp FPushwooshModule& pushwoosh = FPushwooshModule::Get(); pushwoosh.SetTags("{ \"intTag\" : 1, \"stringTag\" : \"example\", \"listTag\" : [ \"a\", \"b\", \"c\" ] }"); ``` [التوثيق](https://github.com/Pushwoosh/pushwoosh-unreal-engine/blob/master/Plugins/Pushwoosh/Documentation/README.md#settags) ```javascript Pushwoosh.setTags({ "key": keyValue, "value": inputValue }); ``` [التوثيق](https://github.com/Pushwoosh/pushwoosh-expo-plugin-sample/blob/main/app/_layout.tsx#L296C17-L296C76) ```objective-c NSDictionary *tags = @{ @"Alias" : aliasField.text, @"FavNumber" : @([favNumField.text intValue]), @"price" : [PWTags incrementalTagWithInteger:5], @"List" : @[ @"Item1", @"Item2", @"Item3" ] }; [[PushNotificationManager pushManager] setTags:tags]; ``` [التوثيق](https://github.com/Pushwoosh/pushwoosh-dotnet/blob/c40c0fd60cb5fe5c5016c46d677a779a5600f45f/PushwooshSDK.DotNet.iOS.Bindings/PushwooshFramework.xcframework/ios-arm64/PushwooshFramework.framework/Headers/PushNotificationManager.h#L380) **معلمات الإدخال** **Tags** – قائمة بسجلات العلامات تحتوي على `TagName` و `TagValue`. - يجب أن يكون `TagName` دائمًا من نوع **Text**. - يمكن أن يكون `TagValue` **Text, Integer, Boolean, Date**, إلخ. [اعرف المزيد](/ar/developer/pushwoosh-sdk/cross-platform-frameworks/outsystems/pushwoosh-outsystems-plugin-client-actions#settags) ### تعيين العلامات عبر API بينما في معظم الحالات (99%)، يتم تعيين العلامات من التطبيق، يمكنك أيضًا تعيين العلامات عبر Pushwoosh API. فيما يلي مثال على طلب نموذجي إلى نقطة نهاية [`/setTags`](/ar/developer/api-reference/device-api#settags): POST `https://api.pushwoosh.com/json/1.3/setTags` ```json { "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](/ar/developer/api-reference/device-api/#settags) ## استخدام علامة **City** الافتراضية يتم تحديد موقع الجهاز بناءً على عنوان IP الخاص به في اللحظة التي تم فيها تشغيل تطبيقك على هذا الجهاز لآخر مرة. يقدم GeoIP بيانات الموقع إلى Pushwoosh، ويحفظ Pushwoosh الموقع المستلم من GeoIP كقيمة لعلامة City لجهاز معين. في بعض الحالات، يختلف الموقع الذي يقدمه GeoIP عن اسم المدينة — على سبيل المثال، عندما يشير إلى منطقة من مدينة أو وحدة إدارية أخرى. يرجى توخي الحذر عند استخدام علامة City الافتراضية لأغراض التقسيم: تأكد من تحديد القيم المناسبة. على سبيل المثال، إذا كنت ستستهدف المستخدمين من ميونيخ، فيجب عليك تغطيتها بمجموعة من قيم علامة City، بما في ذلك "Munich" نفسها (مع جميع القيم المقابلة، مثل المتغيرات المختلفة للتهجئة التي يمكن أن يعيدها GeoIP ويتم حفظها كقيم للعلامة) والعديد من المناطق المجاورة.