استخدام Braze Connected Content لإنشاء حملات مخصصة

تقوم ميزة Connected Content من Braze بجلب البيانات مباشرة من نقطة النهاية الخاصة بك إلى الرسالة في وقت العرض، لذا تعتمد كل حملة تستخدمها على نقطة النهاية تلك في وقت الإرسال. خطط لحجم طلبات يتجاوز عدد الرسائل، ووقت استجابة أقل من ثانيتين، وحجم أقصى يبلغ 1 ميجابايت. حدد ما يجب أن يحدث عند فشل الطلب قبل الإرسال الأول.

ما الذي تفعله ميزة Connected Content من Braze أثناء إعداد الرسالة؟

ترسل Connected Content طلباً عبر الويب من Braze إلى نقطة النهاية أثناء إعداد الرسالة، ثم تدرج الاستجابة باستخدام Liquid. يمكنك كتابة الطلب باستخدام الوسمconnected_contentوحفظ الاستجابة في متغير باستخدام:save.

يعد التوقيت جزءاً أساسياً من التصميم. يتم تنفيذ Connected Content عند إعداد الرسالة؛ وبالنسبة لرسائل داخل التطبيق، يحدث هذا في وقت عرضها. يتم تشغيل الطلبات داخل القالب من الأعلى إلى الأسفل، لذا يمكن لطلب لاحق استخدام متغير تم تعريفه بواسطة طلب سابق.

تنسيق الاستجابة مهم أيضاً. إذا أعادت نقطة النهاية بيانات بتنسيق JSON، تقوم Braze بتحليلها في متغير. وإذا أعادت نصاً، فسيتم إدراجه في موضع الوسم. المتغير المحفوظ متاح فقط داخل الحقل الذي يحتوي على الطلب، لذا يتطلب سطر الموضوع والنص الأساسي طلباً منفصلاً لكل منهما.

كيف يمكنك إرسال بيانات المستخدم إلى نقطة النهاية بشكل آمن؟

تسمح لك Braze بوضع سمات الملف الشخصي في رابط URL الخاص بالطلب. يجب وضع قيم السمات بين${}، ويجب عليك استخدام عامل التصفيةurl_param_escapeللقيم التي تحتوي على أحرف خاصة، مثل علامة @ في عنوان البريد الإلكتروني.

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

الممارسة الأكثر أماناً هي إرسال معرّف لا يشكل بحد ذاته بيانات شخصية مباشرة، مثل معرف داخلي، ثم السماح لنقطة النهاية بجلب الباقي. إذا كانت معرّفات المستخدمين عبارة عن عناوين بريد إلكتروني أو أرقام هواتف، فإن الملاحظة نفسها تنطبق.

تتطلب الاستجابة نفس المستوى من العناية. تذكر Braze أنها لا تسجل أو تخزن نصوص الاستجابة بشكل دائم، ولكنها قد تحتفظ بها مؤقتاً أثناء المعالجة. الرسالة النهائية مسألة مختلفة. عند تفعيل أرشفة الرسائل، قد تتم كتابة الرسالة في التخزين السحابي، وسيتم تضمين بيانات Connected Content في النسخة المؤرشفة. بعد التسليم، قد يظل المحتوى على أجهزة المستخدمين لفترة غير محددة. في بطاقات المحتوى، تخزن Braze المحتوى المعروض في قاعدة بياناتها حتى تنتهي صلاحية البطاقة. لذلك، قد تظل البيانات الشخصية التي تعيدها نقطة النهاية موجودة بعد اكتمال الإرسال.

تعتمد المعرّفات والحقول المقبولة على القواعد المطبقة على بياناتك. لا تحدد هذه المقالة ذلك، لذا راجعها قبل اختيار ما تريد تضمينه في رابط URL أو الاستجابة.

لماذا تجري Braze طلبات Connected Content أكثر من عدد الرسائل؟

توضح Braze أن الإرسال الواحد لا يساوي طلب Connected Content واحداً، وأنها لا تضمن نسبة 1:1 بين الرسائل والطلبات. يجب أن تتحمل نقطة النهاية طلبات أكثر من عدد المستلمين.

السببما توثقه Brazeرسالة بريد متعددة الأجزاءتجهيز مستقل لمتن HTML والنص العادي ونسخة AMP إن وجدتالتحقق وإعادة المحاولةقد تُجهّز حمولة الرسالة عدة مرات لكل مستلمتوقيت القناةالتجهيز وقت الإرسال، وللرسائل داخل التطبيق وقت الظهور

تذكر Braze أن ضرب عدد المستلمين في اثنين أو ثلاثة يُستخدم غالباً كتقدير احتياطي للبريد. لا يوجد حد معدل مستقل لـ Connected Content، لأن حجم الطلبات يتناسب مع سرعة إرسال الرسائل. لذلك فإن خفض سرعة تسليم الحملة وسيلة لحماية نقطة النهاية.

سجّل نتيجة مهمة في التصميم: قد تستدعي Braze نقطة النهاية أكثر من مرة للمستلم نفسه، فيجب أن يكون تكرار الاستدعاء آمناً. افصل العدادات واستهلاك القسائم وأي آثار جانبية أخرى عن نقطة Connected Content، وضعها في طلب مستقل يعمل مرة واحدة.

ما الحدود التي يجب أن تستوفيها نقطة النهاية؟

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

الحدالسلوك الموثقوقت الاستجابةأقل من ثانيتين، وإلا لا يُدرج المحتوىحجم الاستجابة1 MBإعادة التوجيهلا تُتبع؛ تُعد استجابات 2xx وحدها ناجحةالمنافذ80 و443 فقطالطرقGET وPOST؛ وGET فقط لـ Bannersاستجابة 404تعرض Braze سلسلة فارغةاستجابة 500 أو502يفشل الطلب ضمن منطق إعادة المحاولة

قاعدة إعادة التوجيه تسبب التباساً. توضح Braze أن Postman وغيره يتبع إعادة التوجيه تلقائياً غالباً، لذا قد يعمل URL فيه ويُنتج محتوى فارغاً في Braze. اجعل الوسم يشير مباشرةً إلى العنوان النهائي.

ماذا يحدث عند فشل طلب Connected Content؟

لديك ثلاث طرق موثقة للتعامل مع الفشل، ولكل منها سلوك مختلف. اختر السياسة لكل رسالة قبل بنائها.

السياسةكيفية إعدادهاما يتلقاه المستلمالحدود محتوى بديلشرط Liquid على المتغير المحفوظ مع نص افتراضيرسالة بمحتوى عاممنطق تحدده أنت؛ استجابة 404 تعرض سلسلة فارغة أصلاً إعادة المحاولةالخيار:retryرسالة متأخرة أثناء المحاولات، أو إلغاء إذا فشلت جميعهاحتى خمس محاولات؛ غير متاح للرسائل داخل التطبيق أو Banners؛ للإرسال وليس المعاينة الإلغاءabort_message()داخل شرطلا رسالةلا يدخل الإرسال الملغى في عدد الرسائل، ويظهر باسم Liquid abort في Messaging Observability

يضيف Canvas تفصيلاً لإعادة المحاولة. في خطوة Message ينتظر المستلمون في قائمة الإرسال أثناء المحاولات، وإذا فشلت كلها تُلغى الرسالة وينتقل المستخدم إلى الخطوة التالية. وفي خطوتي Context وUser Update يؤدي الفشل بعد المحاولات إلى خروج المستخدم من Canvas.

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

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

{% connected_content https://api.example.com/recommendations?user_id={{${user_id}}} :save connected :retry %}
{% if connected.recommendations.size < 5 %}
  {% abort_message('Could not get enough recommendations') %}
{% endif %}

خيارات الوسم في المثال مأخوذة من صفحات Braze، بينما URL وأسماء الحقول أمثلة تستبدلها بنقطة النهاية الخاصة بك.

تحمي Braze أيضاً الخوادم التي تواجه ضغطاً. عند ارتفاع معدل الفشل خلال دقيقة، يتم إيقاف الطلبات مؤقتاً لمدة دقيقة ومحاكاة استجابة فشل. يشمل الحساب رموز 408 و429 و502 و503 و504 و529. وإذا أردت إعادة محاولة الطلبات المتوقفة، فاستخدم:retry.

كيف يتم تخزين استجابات Connected Content مؤقتاً؟

تخزّن Braze طلبات GET مؤقتاً بشكل افتراضي، ولا تفعل ذلك مع طلبات POST. العمر الافتراضي للذاكرة المؤقتة هو خمس دقائق، ويمكن زيادته باستخدام:cache_max_ageup to four hours, or disable it for a specific request using:no_cache. Responses exceeding 1 MB are not cached.

The cache key consists of the workspace, URL, content type, and request body. The key does not depend on the user ID or campaign, so the response can be reused across users, campaigns, and Canvases within the same workspace when these four elements match. Storage times are indicative; memory is volatile and data may be removed before the specified time, which may lead to a higher number of requests than expected.

This has security implications. If the endpoint personalizes the response for a specific user, the URL or request body must include what makes this response unique. Headers or credentials are not included in Braze cache keys, so a cached response for one user might be used for another if the endpoint infers identity solely from headers or credentials. Place the identifier in the URL or request body, or disable caching using:no_cache.

Braze clarifies that it may bypass caching when highly variable values are included in the tag, and specifies six such values: User ID, Braze ID, email, email address, phone number, and date of birth. Plan the capacity for requests using any of these values as if there were no cache.

Disabling caching comes at a cost. For an endpoint outside the Braze architecture, using:no_cacheplacing the response body in Memcached keeps it in the worker's memory during the processing task for approximately 11 minutes. Braze warns that the endpoint will receive a request for every message, and latency may increase if servers cannot handle sudden spikes in requests.

كيف تختبر Connected Content قبل الإطلاق؟

The Connected Content Debugger displays live requests and responses for each call in Preview and Test mode. Braze made this tool available to everyone on September 17, 2026, following an early access period that began on August 20, 2026. The tool shows the URL, method, status, headers, payload, duration, and whether the response came from the cache.

Check your channel support; Braze notes that the tool is not yet available for all channels, such as KakaoTalk, nor for some authoring surfaces like Content Blocks and the Canvas User Update step.

The retry feature requires a different test, as its logic operates on actual sends, including test sends, rather than previews. The preview may show a message upon failure stating that the content will not appear. To test retries, send a test message.

ما الذي ينبغي تحديده قبل تفعيل أول طلب؟

As a Braze implementation partner, CustomerIK recommends documenting four decisions before building your first template.

Who owns the endpoint, and how is it prepared to accommodate the number of recipients multiplied by two or three for email.
Failure policy for each message: fallback content, retry, or cancel.
Identifiers allowed in the URL and response, and where the final message is saved or archived.
Whether every request is cached, for how long, and what makes the response user-specific within the URL or request body.

بعد الاتفاق عليها، تحول هذه القرارات Connected Content إلى خدمة لها مسؤول واضح.

الأسئلة الشائعة

هل يُحتسب Connected Content ضمن نقاط البيانات؟

Braze clarifies that it does not charge for these API calls and does not count them towards data point usage.

كم يمكن أن تستغرق استجابة نقطة النهاية؟

Braze requires a response in less than two seconds. If the server takes longer than that, the content will not be inserted.

هل يمكن استخدام إعادة المحاولة في رسالة داخل التطبيق؟

Braze clarifies that:retryis not available for in-app messages or banners.

Why do I see more requests than the number of recipients in my logs?

قد تكرر Braze الاستدعاء لكل مستلم، على سبيل المثال لكل جزء من البريد الإلكتروني، ولا تضمن نسبة 1:1 مع الإرسال.

هل تخزّن Braze استجابة نقطة النهاية؟

لا يتم تخزين نصوص الاستجابات بشكل دائم، ولكن قد يتم الاحتفاظ بها مؤقتاً لأغراض المعالجة والتخزين المؤقت. يمكن حفظ الرسالة النهائية من خلال ميزة أرشفة الرسائل (Message Archiving) أو بطاقات المحتوى (Content Cards). وتحتفظ Braze ببيانات الطلب الوصفية، بما في ذلك عنوان URL النهائي، لمدة تصل إلى 30 يوماً.

هل يمكن استخدام استجابة مخزنة لمستخدم معين مع مستخدم آخر؟

يعتمد مفتاح التخزين المؤقت على مساحة العمل، وعنوان URL، ونوع المحتوى، ونص الطلب، وليس على معرّف المستخدم؛ لذا يمكن إعادة استخدام الاستجابة إذا تطابقت هذه العناصر. اجعل البيانات الخاصة بالمستخدم جزءاً من عنوان URL أو نص الطلب، أو استخدم:no_cache.

المصادر

Braze،إجراء طلب واجهة برمجة تطبيقات للمحتوى المتصل (Connected Content API)تاريخ الاطلاع: 1 أكتوبر 2026.
Braze،التخزين المؤقت لاستجابات المحتوى المتصل (Connected Content)تاريخ الاطلاع: 1 أكتوبر 2026.
Braze،استخدام منطق إعادة المحاولة للمحتوى المتصل (Connected Content)تاريخ الاطلاع: 1 أكتوبر 2026.
Braze،إلغاء المحتوى المتصل (Connected Content)تاريخ الاطلاع: 1 أكتوبر 2026.
Braze،متغيرات المحتوى المتصل (Connected Content) المحليةتاريخ الاطلاع: 1 أكتوبر 2026.
Braze،أداة تصحيح أخطاء المحتوى المتصل (Connected Content Debugger)تاريخ الاطلاع: 1 أكتوبر 2026.
Braze،ما الجديد في Brazeتاريخ الاطلاع: 1 أكتوبر 2026.