المنشورات

انشر الإعلانات والفعاليات والعروض على Google وFacebook باستخدام حزمة SDK ‏listingsapi-js.

تنشر دوال المنشورات المحتوى على Google Business Profile وFacebook، ثم تتيح لك متابعة حالة النشر والتحليلات لكل منصة. تتوفر جميع دوال المنشورات مباشرةً على نسخة العميل ListingsAPI.

يتم النشر بشكل غير متزامن: تُرجع استدعاءات الإنشاء status: 'INPROGRESS'، ويُنشر المنشور في الخلفية. استعلم دوريًا باستخدام fetchPost حتى تصبح الحالة SUCCESS، وتحقق من publishDetails[].submissionError لمعرفة حالات الفشل لكل منصة.

bulkPublish

انشر منشورًا واحدًا على Google وFacebook لعدة مواقع في استدعاء واحد. القيمة الافتراضية لـ sites تشمل المنصتين. تُحوَّل الرسالة (أو خريطة النصوص المخصصة لكل منصة) إلى عنصر واحد لكل منصة، وتُرمَّز معرّفات المواقع تلقائيًا، ويُتحقق من صحة الحمولة على جانب العميل قبل أي استدعاء عبر الشبكة (تؤدي الحمولة غير الصالحة إلى طرح ValidationError فورًا).

const result = await client.bulkPublish({name: 'Holiday hours',locationIds: [16808, 16809, 16810],message: 'Open until 10pm through the holidays!',mediaUrl: 'https://cdn.example.com/holiday.jpg',ctaType: 'LEARN_MORE',ctaUrl: 'https://example.com/holiday-hours',});console.log(result.socialPost.id, result.socialPost.status); // INPROGRESS, publishes async

مرّر كائنًا في message لتخصيص النص لكل منصة:

await client.bulkPublish({name: 'Holiday hours',locationIds: [16808, 16809],message: {  GOOGLE: 'Open until 10pm through the holidays. Book online!',  FACEBOOK: 'We are staying open late for the holidays. See you soon!',},});

الخيارات

createAnnouncement

أنشئ منشورًا من نوع ANNOUNCEMENT: رسالة بسيطة مع إمكانية إضافة دعوة إلى اتخاذ إجراء ووسائط. تقبل الدالة الخيارات نفسها التي تقبلها bulkPublish باستثناء postType وcontextInfo؛ وتكون القيمة الافتراضية لـ sites هنا هي ['GOOGLE'].

await client.createAnnouncement({name: 'Grand Opening',locationIds: [16808],message: 'Acme Dental is now open in the Mission!',sites: ['GOOGLE'],ctaType: 'LEARN_MORE',ctaUrl: 'https://example.com/opening',});

createEvent

أنشئ منشورًا من نوع EVENT بعنوان وفترة محددة ببداية ونهاية. الحقل title مطلوب (تشترطه Google)؛ والحقلان startDay وendDay تاريخان بصيغة YYYY-MM-DD، أما startTime وendTime فهما وقتان اختياريان للعرض. القيمة الافتراضية لـ sites هي ['GOOGLE'].

await client.createEvent({name: 'Live music',locationIds: [16808],message: 'Join us Friday for live jazz!',title: 'Jazz Night',startDay: '2026-08-01',endDay: '2026-08-01',startTime: '7:00pm',endTime: '10:00pm',});

createOffer

أنشئ منشورًا من نوع OFFER يتضمن قسيمة وخصمًا وشروطًا. الحقل title مطلوب؛ وجميع حقول العرض الأخرى اختيارية. القيمة الافتراضية لـ sites هي ['GOOGLE'].

await client.createOffer({name: 'Summer sale',locationIds: [16808],message: '20% off whitening all week!',title: 'Summer Sale',couponCode: 'SUMMER20',discount: '20%',redeemUrl: 'https://example.com/sale',termsConditions: 'One per customer.',startDay: '2026-08-01',endDay: '2026-08-07',});

خيارات العرض

createPost

أنشئ منشورًا من جسم خام يتكون من حقول غير متداخلة، دون التحقق من صحته على جانب العميل. تضع الدالة ما تمرّره داخل الكائن input الذي تتطلبه واجهة API، لذا يكون الجسم المُرسل عبر الشبكة هو {"input": {...}}؛ أما الجسم الذي تكون جميع حقوله في المستوى الأعلى فيُرفض بحالة HTTP 400. يُفضَّل استخدام createAnnouncement أو createEvent أو createOffer، فهي تُنشئ هذا الجسم وتتحقق من صحته نيابةً عنك.

await client.createPost({postName: 'Grand Opening',locationIds: ['TG9jYXRpb246MTY4MDg='],postType: 'ANNOUNCEMENT',postSites: ['GOOGLE'],postMessage: [{ site: 'GOOGLE', message: 'We are now open!' }],});

fetchPost

اجلب منشورًا مع محتواه وحالة النشر لكل منصة والتحليلات. استخدم هذه الدالة للاستعلام دوريًا عن منشور بحالة INPROGRESS حتى يُنشر.

let post = await client.fetchPost('U29jaWFsUG9zdDo0NDEyMg=='); while (post.status === 'INPROGRESS') {await new Promise((resolve) => setTimeout(resolve, 5000));post = await client.fetchPost('U29jaWFsUG9zdDo0NDEyMg==');} for (const detail of post.publishDetails ?? []) {if (detail.submissionError) {  console.log('failed:', detail.submissionError);}}

deletePost

احذف منشورًا وأزله من كل منصة نُشر عليها.

await client.deletePost('U29jaWFsUG9zdDo0NDEyMg==');

fetchLocationPosts

اعرض قائمة بحملات المنشورات التي تستهدف موقعًا. تستخدم الدالة ترقيم الصفحات بالإزاحة (page وperPage)، وتكون القيمة الناتجة عند اكتمالها هي postsByLocation.

يرفض هذا المسار tag، لذا تقبل حزمة SDK هذا الخيار منذ الإصدار 0.3.2 للتوافق مع الإصدارات السابقة، ولا ترسله عبر الشبكة مطلقًا. استخدم fetchLocationBulkPosts عندما تحتاج إلى التصفية حسب الوسوم.

const posts = await client.fetchLocationPosts(16808, { page: 1, perPage: 10 });

الخيارات

fetchBulkPost

اجلب حملة نشر جماعي مع حالة النشر والتحليلات لكل موقع.

const bulk = await client.fetchBulkPost('QnVsa1Bvc3Q6OTk=');

fetchLocationBulkPosts

اعرض قائمة بحملات النشر الجماعي (متعددة المواقع) التي تشمل موقعًا. تقبل الدالة الخيارات نفسها التي تقبلها fetchLocationPosts.

const campaigns = await client.fetchLocationBulkPosts(16808, { page: 1, perPage: 10 });

موارد ذات صلة

• المواقع، البحث عن معرّفات المواقع
• معالجة الأخطاء، ValidationError ورموز أخطاء المنصة