‏إعلانات كتالوج Advantage+‏

إعلانات الفنادق - الكتالوجات وقائمة المنتجات

لترويج مخزون منتجات الفنادق على Facebook، يجب مشاركة معلومات وفنادقك مع Facebook. ويمكنك القيام بذلك من خلال إنشاء كتالوج للفنادق ثم ملؤه بالفنادق. وتوجد طريقتان لملء الكتالوج الخاص بك وتحديثه:

يمكنك إنشاء كتالوجات الفنادق الخاصة بك وإدارتها في مدير المعاملات التجارية.

لاستخدام واجهة API في إدارة الكتالوج:

  1. إنشاء كتالوج فندق
  2. إنشاء مجموعات المنتجات من كتالوج فندقك
  3. ربط الكتالوج بمصادر الأحداث

قوائم منتجات الفنادق - تحميل فنادقك على Facebook

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

تنسيقات قوائم الفنادق المدعومة

CSV

عينة من CSV | عينة من TSV (بلا تنسيق) | عينة من TSV (بنمط JSON)

  • يجب أن يحتوي الصف الأول على أسماء الحقول المُختارة بالترتيب الذي تتوفر به القيم. تقوم الصفوف التالية بعد ذلك بتقديم القيم ذات الصلة لكل فندق.
  • يجب تضمين الحقول التي تحتوي على مسافة أو فواصل داخل "علامتي تنصيص".
  • ويمكن تقديم الحقول المتداخلة أو ذات القيم المتعددة، مثل أو address أو neighborhood أو image باستخدام قيم بتشفير لغة JSON أو من خلال مجموعة من أعمدة النص العادي "بلا تنسيق" تتم تسميتها باستخدام بنية مسار لغة JSON، مثل address.city وneighborhood[0] وimage[0].url وimage[0].tag[0] وimage[0].tag[1]. ويمكن استخدام المصطلحين بالتبادل في الملف نفسه.

XML

عينة من XML

  • تتضمن عقدة <listings> XML الجذرية مجموعة من عُقد <listing> تمثل كل واحدة منها فندقًا.
  • يحب أن يبدأ الملف بعلامة توضيح <?xml صالحة.

يقوم محلل القوائم تلقائيًا باكتشاف تشفيرات النصوص UTF8 وUTF16 وUTF32، ويقوم بتعيين القيمة الافتراضية على LATIN1 إذا واجه سلسلة بايت غير متوقعة. يمكنك تقديم النص في قيم الحقول بأي لغة، بينما يجب أن تكون أسماء الحقول مطابقة للأسماء التالية وباللغة الإنجليزية فقط.

الحقول المدعومة — إعلانات الفنادق

صُممت الحقول المدعومة التالية للعناصر التي تضيفها إلى كتالوج المنتجات.

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

الحقل والنوعالوصف

hotel_id

النوع: string (سلسلة)

مطلوب.

الحد الأقصى للطول: 100

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

المثال: FB_hotel_1234

room_id

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

أدخل معرفًا فريدًا لنوع غرفة الفندق. ويكون الحد الأقصى لعدد الحروف: 100 المثال: FB_hotel_room_1234

name

النوع: string (سلسلة)

مطلوب.

يمثل الاسم الأكثر شيوعًا للفندق.

المثال: Facebook Hotel

description

النوع: string (سلسلة)

مطلوب.

الحد الأقصى للحجم: 5000

يمثل وصفًا لموجز الفندق.

المثال: Only 30 minutes away from San Francisco.

checkin_date

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

يمثل تاريخ الدخول للإقامة بالفندق. يمكنك إضافة 180 يومًا كحد أقصى من تاريخ تحميل قائمة المنتجات. يستخدم معيار ISO-8601 (YYYY-MM-DD).

مثال: 2017-08-01

length_of_stay

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

يمثل عدد ليالي الإقامة بالفندق.

المثال: 7

base_price

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

يمثل السعر الأساسي للإقامة ليلة واحدة في غرفة فندقية. تأكد من إضافة نوع العملة إلى السعر (على سبيل المثال، استخدام العملة USD للدولار الأمريكي). يمكنك تنسيق السعر كتكلفة متبوعة بكود العملة ISO مع وضع مسافة بين التكلفة والعملة.

مثال: 199.00 EUR

price

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

يمثل إجمالي أسعار الإقامة بالفندق استنادًا إلى checkin_date وlength_of_stay. يمكنك تنسيق السعر كتكلفة متبوعة بكود العملة ISO مع وضع مسافة بين التكلفة والعملة.

مثال: 1393.00 USD

tax

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

معدل الضريبة المطبق على السعر. يمكنك تنسيق السعر كتكلفة متبوعة بكود العملة ISO مع وضع مسافة بين التكلفة والعملة.

مثال: 14.00 USD

fees

النوع: string (سلسلة)

مطلوب في حالة إضافة معلومات غرفة الفندق.

الرسوم المطبقة على السعر. يمكنك تنسيق السعر كتكلفة متبوعة بكود العملة ISO مع وضع مسافة بين التكلفة والعملة.

مثال: 253.00 USD

url

النوع: string (سلسلة)

مطلوب.

يمثل رابطًا للموقع الخارجي الذي يمكنك من خلاله حجز غرفة فندقية. ويمكنك أيضًا تحديد عنوان URL على مستوى الإعلان باستخدام template_url_spec. ويكون لعناوين URL على مستوى الإعلان أولوية على عناوين URL الموجودة في قوائم المنتجات.

المثال: https://www.facebook.com/hotel

image[0].url

النوع: object (كائن)

راجع معلمات كائن الصورة.

image[0].tag

النوع: object (كائن)

راجع معلمات كائن الصورة.

brand

النوع: string (سلسلة)

مطلوب.

يمثل اسم العلامة التجارية لسلسلة الفندق.

المثال: Hilton

address

النوع: object (كائن)

راجع معلمات كائن العنوان.

neighborhood[0]

النوع: string (سلسلة)

مطلوب.

الحد الأقصى لعدد الأحياء المجاورة المسموح به: 20

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

المثال: Belle Haven

latitude

النوع: float (رقم عشري)

مطلوب.

يمثل خط العرض حيث يوجد الفندق.

مثال: 37.484100

longitude

النوع: float (رقم عشري)

مطلوب.

يمثل خط الطول حيث يوجد الفندق.

مثال: -122.148252

sale_price

النوع: string (سلسلة)

اختياري.

يمثل سعر الخصم للإقامة بغرفة فندقية استنادًا إلى checkin_date وlength_of_stay. استخدم هذا عندما تريد الإعلان عن الخصومات على السعر الأصلي للفندق. تأكد من إضافة نوع العملة إلى السعر (على سبيل المثال، العملة USD للدولار الأمريكي). وتأكد من أن sale_price للفندق أقل من base_price. يمكنك تنسيق السعر كتكلفة متبوعة بكود العملة بتنسيق ISO، مع وضع مسافة بين التكلفة والعملة.

مثال: 149.00 USD

guest_ratings.score

النوع: object (كائن)

راجع معلمات كائن تقييم الضيوف.

guest_ratings.rating_system

النوع: object (كائن)

راجع معلمات كائن تقييم الضيوف.

star_rating

النوع: float (رقم عشري)

راجع معلمات كائن تقييم الضيوف.

loyalty_program

النوع: string (سلسلة)

اختياري.

يمثل برنامج الولاء الذي تستخدمه لربح نقاط للإقامة في الفندق.

المثال: Premium program

margin_level

النوع: integer (عدد صحيح)

اختياري.

يمثل مؤشر أرباح الفندق وتتراوح القيمة من 1 إلى 10.

المثال: 9

phone

النوع: string (سلسلة)

اختياري.

يمثل رقم الهاتف الأساسي للفندق.

المثال: +61 296027455

applink

النوع: object (كائن)

اختياري.

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

  1. على مستوى الإعلان باستخدام template_url_spec
  2. هنا في قائمة المنتجات باستخدام كائن Applink
  3. من خلال إضافة علامات تعريف رابط التطبيق إلى موقعك على الويب.

تعرف على المزيد حول الروابط لمواضع معينة للمنتجات.

priority

النوع: integer (عدد صحيح)

اختياري.

يمثل مؤشر أولوية الفندق وتتراوح القيمة من 0 (أدنى أولوية) إلى 5 (أعلى أولوية). المثال: 5

category

النوع: string (سلسلة)

اختياري.

يمثل نوع الخاصية. ويمكن أن تكون الفئة نوعًا من الوصف الداخلي المطلوب. المثال: Resort، Day Room

number_of_rooms

النوع: integer (عدد صحيح)

اختياري.

يمثل إجمالي عدد الغرف/الوحدات في قائمة الفنادق هذه.

المثال: 150

status

النوع: string (سلسلة)

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


المثال: active


ملاحظة: قد تقوم بعض المنصات الشريكة، مثل Shopify بمزامنة العناصر مع الكتالوج لديك من خلال حالة تُسمى staging، والتي يتشابه سلوكها مع سلوك الحالة archived.

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

معلمات كائن الصورة


اسم الحقل والنوعالوصف

url

النوع: string (سلسلة)

مطلوب.

الحد الأقصى للعناصر: 20.

يمثل رابط عنوان URL إلى صورة العنصر الذي سيظهر في إعلاناتك. واتبع مواصفات الصورة التالية:

  • يجب أن تكون كل الصور بتنسيق JPG أو GIF أو PNG.

  • بالنسبة للإعلانات الدوّارة وإعلانات المجموعة: تظهر الصور بتنسيق مربع بنسبة العرض إلى الارتفاع (1:1). الحد الأدنى لحجم الصورة هو 500 × 500 بيكسل. نوصي باستخدام صور بحجم 1024 × 1024 بيكسل للحصول على أفضل جودة.

  • بالنسبة للإعلانات التي تتضمن صورة واحدة: تظهر الصور بنسبة عرض إلى ارتفاع 1.91:1. والحد الأدنى لحجم الصورة هو 500 × 500 بيكسل. نوصي باستخدام صور بحجم 1200 × 628 بيكسل للحصول على أفضل جودة.

  • إذا كان لديك أكثر من صورة واحدة، يمكنك إضافة أعمدة إضافية لكل صورة واستخدام بنية مسار بلغة JSON في كل اسم من أسماء الأعمدة للإشارة إلى عدد الصور.

المثال: image[0].url; image[1].url

المثال: https://www.facebook.com/facebook_hotel.jpg

tag

النوع: string (سلسلة)

اختياري.

الإشارة التي تم إلحاقها بالصورة وتعرض الموجود داخل الصورة. يمكن وضع عدة إشارات مرتبطة بالصورة.

الأمثلة: Fitness Center، Swimming Pool، suite

INSTAGRAM_STANDARD_PREFERRED - يتيح للمُعلنين وضع إشارة على صورة معينة في قائمة المنتجات الخاصة بهم باعتبارها الصورة الافتراضية المطلوب استخدامها في Instagram. وتكون هذه الإشارة حساسة لحالة الأحرف.


معلمات كائن العنوان

يمكن تقديم الحقول المتداخلة أو ذات القيم المتعددة، مثل address باستخدام قيم بتشفير بلغة JSON أو من خلال مجموعة من أعمدة النص العادي "بلا تنسيق" تتم تسميتها باستخدام بنية مسار JSON، مثل address.region. يمكن استخدام المصطلحين بالتبادل في الملف نفسه.


اسم الحقل والنوعالوصف

addr1 (address.addr1)

النوع: object (كائن)

مطلوب.

يمثل عنوان الشارع الرئيسي للفندق.

المثال: 1600 Pennsylvania Avenue

address.addr2

النوع: object (كائن)

اختياري.

يمثل عنوان الشارع الفرعي للفندق.

المثال: Apartment 1

address.addr3

النوع: object (كائن)

اختياري.

يمثل عنوان الشارع الثالث للفندق.

المثال: Downstairs

address.city_id (city_id)

النوع: string (سلسلة)

اختياري.

يمثل القيمة المطلوب استخدامها في عنوان URL الخاص بالرابط لموضع معين template_url في تصميم الإعلان.

مثال: 12345

address.city (city)

النوع: string (سلسلة)

مطلوب.

يمثل المدينة التي يوجد بها الفندق.

مثال: New York

address.region (region)

النوع: string (سلسلة)

مطلوب.

يمثل الولاية أو المقاطعة أو الإقليم حيث يوجد الفندق.

مثال: California

address.country (country)

النوع: string (سلسلة)

مطلوب.

يمثل البلد الذي يوجد به الفندق.

مثال: United States

address.postal_code (postal_code)

النوع: string (سلسلة)

مطلوب للبلدان التي لها نظام رمز بريدي.

يمثل الرمز البريدي أو رمز zip للفندق.

الأمثلة: 94125، NW1 3FG

معلمات كائن تقييم الضيوف


اسم الحقل والنوعالوصف

guest_ratings.score (score)

النوع: object (كائن)

اختياري.

يمثل إجمالي عدد الأشخاص الذين قاموا بتقييم فندقك. وإذا تم التحديد، فيجب عليك أيضًا توفير score وmax_score وnumber_of_reviewers وrating_system.

المثال: 9.0/10

guest_ratings.number_of_reviewers (number_of_reviewers) النوع: int (عدد صحيح)

اختياري.

يمثل إجمالي عدد الأشخاص الذين قاموا بتقييم هذا الفندق.

المثال: 5287

guest_ratings.rating_system (rating_system)

النوع: string (سلسلة)

اختياري.

يمثل النظام الذي تستخدمه لتقييم الضيوف.

الأمثلة: Expedia، TripAdvisor

max_score

النوع: int

مطلوب.

الحد الأقصى لقيمة نقاط تقييم الفندق. ويجب أن يكون أكبر من أو يساوي 0 وأقل من أو يساوي 100.

المثال: 10

واجهة API الفندق - إنشاء الفنادق وإدارتها مباشرة

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

تتناسب الأقسام التالية معك فقط لإدارة كتالوجاتك باستخدام واجهة API هذه.

إنشاء كتالوج الفندق باستخدام واجهة API

المستندات المرجعية

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

لإنشاء كتالوج فندق لإعلانات الفنادق، قم بتعيين vertical إلى hotels:

curl -X POST \
  -F 'name="Test Hotel Catalog"' \
  -F 'vertical="hotels"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v10.0/BUSINESS_ID/owned_product_catalogs

تحميل قوائم منتجات الفنادق عبر واجهة API

بمجرد الانتهاء من إنشاء الكتالوج، يجب تحميل قائمة (قوائم) منتجات الفنادق إلى Facebook. ويمكنك استخدام واجهة API لإنشاء كائن قائمة لكل قائمة تريد تحميلها. ندعم عمليات التحميل المباشرة والمجدولة.

فلترة كتالوج الفنادق لمجموعات الفنادق

المستندات المرجعية

مجموعة الفنادق هي مجموعة فرعية من كتالوج منتجاتك. ولإعداد إعلانات الفنادق، تحتاج إلى مجموعة فنادق. ولذلك، تحتاج على الأقل إلى إنشاء مجموعة.

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

لإنشاء مجموعة فنادق تحتوي على كل الفنادق التي تتضمن 'عينة من علامة تجارية' مذكورة في الحقل brand:

curl -X POST \
  -F 'name="Test Hotel Set"' \
  -F 'filter={
       "brand": {
         "i_contains": "sample brand"
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/<PRODUCT_CATALOG_ID>/product_sets
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const ProductCatalog = bizSdk.ProductCatalog;
const ProductSet = bizSdk.ProductSet;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<PRODUCT_CATALOG_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'Test Hotel Set',
  'filter' : {'brand':{'i_contains':'sample brand'}},
};
const product_sets = (new ProductCatalog(id)).createProductSet(
  fields,
  params
);
logApiCallResult('product_sets api call complete.', product_sets);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\ProductCatalog;
use FacebookAds\Object\ProductSet;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<PRODUCT_CATALOG_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'Test Hotel Set',
  'filter' => array('brand' => array('i_contains' => 'sample brand')),
);
echo json_encode((new ProductCatalog($id))->createProductSet(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.productcatalog import ProductCatalog
from facebook_business.adobjects.productset import ProductSet
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<PRODUCT_CATALOG_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'Test Hotel Set',
  'filter': {'brand':{'i_contains':'sample brand'}},
}
print ProductCatalog(id).create_product_set(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<PRODUCT_CATALOG_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new ProductCatalog(id, context).createProductSet()
      .setName(\"Test Hotel Set\")
      .setFilter(\"{\\"brand\\":{\\"i_contains\\":\\"sample brand\\"}}\")
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<PRODUCT_CATALOG_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

product_catalog = FacebookAds::ProductCatalog.get(id)
product_sets = product_catalog.product_sets.create({
    name: 'Test Hotel Set',
    filter: {'brand':{'i_contains':'sample brand'}},
})

تتكون المعلمة filter من البيانات وعناصر التشغيل التالية:

عناصر التشغيلنوع الفلتر

i_contains

يحتوي على سلسلة فرعية. عنصر التشغيل حساس لحالة الأحرف.

i_not_contains

لا يحتوي على سلسلة فرعية. عنصر التشغيل حساس لحالة الأحرف.

contains

يحتوي على سلسلة فرعية. عنصر التشغيل حساس لحالة الأحرف.

not_contains

لا يحتوي على سلسلة فرعية. عنصر التشغيل حساس لحالة الأحرف.

eq

يساوي. عنصر التشغيل حساس لحالة الأحرف.

neq

لا يساوي. عنصر التشغيل حساس لحالة الأحرف.

lt

أقل من. للحقول الرقمية فقط.

lte

أقل من أو يساوي. للحقول الرقمية فقط.

gt

أكبر من. للحقول الرقمية فقط.

gte

أكبر من أو يساوي. للحقول الرقمية فقط.

البياناتالبيانات التي تتم فلترتها.

hotel_id

المعرف الفريد للفندق في الكتالوج.

brand

يمثل العلامة التجارية لسلسلة الفندق.

base_price_amount

أفضل سعر لليلة لهذا الفندق. يكون السعر بالسنت (4999 يشير إلى 49.99 دولارًا أمريكيًا).

sale_price_amount

يمثل سعر الخصم للإقامة ليلة واحدة في هذا الفندق. يكون السعر بالسنت (4999 يشير إلى 49.99 دولارًا أمريكيًا).

currency

العملة

city

يمثل المدينة التي يوجد بها الفندق.

country

يمثل البلد الذي يوجد به الفندق.

name

يمثل الاسم الأكثر شيوعًا للفندق.

star_rating

تقييم الفندق بالنجوم. تقع القيم الصالحة بين 1 و5 ويجب أن تكون مضاعفات للقيمة 0.5.