Skip to main content
يربط الوضع المباشر (Direct Mode) شبكة اجتماعية واحدة في كل مرة، من زر في لوحة التحكم الخاصة بك. تُنشئ جلسة ربط لتلك الشبكة، وتفتح عنوان URL الذي تعيده في نافذة منبثقة، وتسمع صفحتك ما حدث. مستخدمك لا يرى أبدًا صفحة تسرد كل الشبكات، ولا يغادر تطبيقك لمدة أطول مما يستغرقه تسجيل دخول الشبكة نفسها.

أي سطح تريد

ثلاثة أشكال، والأول والثاني هما التكامل نفسه. هذه الصفحة هي التي تبنيها بنفسك.
الوضع المباشر هو النافذة المنبثقة في الصف الثالث دون السكربت الخاص بنا. إذا كانت صفحتك تستطيع تحميل السكربت، فإن الأداة تنجز عنك كل ما في هذه الصفحة — فهي تفتح النافذة المنبثقة وتراقبها بنفسها، وتستطيع تضمين الإطارات أيضًا. الوضع المباشر هو ما تريده عندما يتعذر على صفحتك تحميل سكربت من طرف ثالث، أو عندما يكون السطح تطبيقًا أصليًا لا متصفحًا.
A customer dashboard with its own Connect buttons and an Ayrshare popup showing the Facebook hand-off screen

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

ما الذي تبنيه

أربع خطوات. الأولى على خادمك، والباقي في صفحتك.
1

أنشئ جلسة لشبكة واحدة

من خادمك الخلفي، استدعِ إنشاء Link Session مع mode: "connect" وnetwork وorigin الذي تعمل عليه صفحتك.
Your backend
يُعاد إليك url يشير إلى صفحة ربط لشبكة واحدة، ولا token — فالتوكن داخل عنوان URL. تعامل مع عنوان URL بأكمله كما تتعامل مع كلمة المرور: فهو يُسجّل دخول مستخدمك إلى User Profile الخاص به.
أنشئ الجلسة على خادمك، وليس في المتصفح أبدًا. الاستدعاء يحتاج إلى مفتاح API الخاص بك.
2

افتحه في معالج النقر، بشكل متزامن

يجب أن تُفتح النافذة المنبثقة بـ window.open داخل معالج النقر نفسه. لا يسمح المتصفح بنافذة منبثقة إلا وهو لا يزال يعالج نقرة مستخدمك، وهذا الإذن لا ينجو من await — لذا فإن جلب عنوان URL أولًا ثم فتحه في الاستدعاء الراجع (callback) يُحجب حجبًا شبه مؤكد.اجلب عنوان URL عند عرض الزر، أو عندما يمرّر مستخدمك المؤشر فوقه. بحلول وقت النقر ينبغي أن يكون لديك بالفعل.
Your page
3

استمع إلى النتيجة

لأنك مرّرت origin، ترسل النافذة المنبثقة حدثًا إلى صفحتك عن كل ما يقع فيها: connect:success وconnect:error وconnect:cancelled، وأحداث تقدّم بينها. يصل واحد بالضبط من تلك الثلاثة لكل عملية ربط.تحوي أحداث اكتمال الربط جدول الأحداث الكامل ومستمعًا جاهزًا للنسخ واللصق — listenForOutcome أعلاه هو ذلك المقتطف. جزآن منه يسهل إغفالهما وكلاهما يسبب أخطاء حقيقية:
  • تحقق من event.origin مقابل أصل عنوان URL الذي فتحته. يمكن لأي صفحة إرسال رسالة إلى نافذتك، والأصل هو الجزء الوحيد من الرسالة الذي لا يمكن تزويره.
  • استطلع popup.closed، مع مهلة سماح قصيرة قبل أن تستنتج أي شيء. النافذة المنبثقة التي أغلقها مستخدمك يدويًا لا ترسل شيئًا إطلاقًا، ومن دون مهلة السماح قد يُبلَّغ عن ربط ناجح على أنه إلغاء.
4

عالج كل نهاية

أضف &autoClose=false إلى عنوان URL أثناء البناء. تبقى النافذة المنبثقة عندئذٍ مفتوحة بعد كل نتيجة بدلًا من أن تُغلق نفسها، فتستطيع قراءة ما تقوله.

ملاحظات لكل شبكة

معظم الشبكات نافذة منبثقة واحدة ولا شيء غيرها: ينقر مستخدمك، ويفوّض عند الشبكة، وتُغلق النافذة. هذه هي الاستثناءات الجديرة بالمعرفة قبل البناء.
تستخدم X في الوضع المباشر بيانات اعتماد تطبيق X Developer الخاص بك، المزوَّدة عند إنشاء الجلسة عبر الترويستين X-Twitter-OAuth1-Api-Key وX-Twitter-OAuth1-Api-Secret على إنشاء Link Session.الجلسة المُنشأة لـ twitter أو x بدون هاتين الترويستين تُرفض عند فتح النافذة المنبثقة: يُخبَر مستخدمك بأن الاتصال غير متاح ولا يُعرض له أي نموذج، وتتلقى صفحتك connect:error مع message وبدون code. وهذا مقصود. فبيانات الاعتماد المفقودة خاصتك، لا خاصة مستخدمك، ويجب ألا يُطلب من المستخدمين النهائيين إدخال مفاتيح API الخاصة بك أبدًا.قارن ذلك بـ Bluesky، حيث كلمة مرور التطبيق هي بيانات اعتماد المستخدم النهائي نفسه — تلك تجمعها صفحة الربط فعلًا، في نموذج داخل النافذة المنبثقة.
يعرض network: "facebook" زرًا واحدًا في النافذة المنبثقة، ويفتح تسجيل دخول Meta نفسه من تلك النقرة — إذ تشترط Meta أن يبدأ تسجيل دخولها بنقرة داخل الصفحة التي تستضيف SDK الخاص بها. ينقر مستخدمك مرتين بدلًا من مرة؛ ولا شيء آخر يختلف.يتصرف Instagram بالطريقة نفسها عندما يُربط عبر Facebook Page — أي عندما تحمل الجلسة instagramLinkMethod: "facebook"، أو عندما يختار إعداد Instagram Login في حسابك ذلك التدفق. أما مع تسجيل دخول Instagram المباشر فلا زر إضافي.
لا يرسل أي منهما مستخدمك إلى تسجيل دخول شبكة. تعرض النافذة المنبثقة محتوى بدلًا من ذلك: نموذج معرّف (handle) وكلمة مرور تطبيق لـ Bluesky، ورمز يُستخدم لـ Telegram. أحداث النتيجة هي نفسها في الحالتين.لا تنتمي X إلى هذه المجموعة. فمع مفاتيحك على الجلسة تكتمل دون مطالبة مستخدمك بأي شيء، وبدونها تُرفض — راجع أعلاه.
يعرض Telegram رمزًا بدلًا من إعادة التوجيه إلى أي مكان، ويكتمل الاتصال عندما يستخدم مستخدمك ذلك الرمز — بعد زوال النافذة المنبثقة. لا يوجد حدث متصفح تنتظره، لذا استطلع الحصول على Link Session وراقب completedNetworks.
ليست Facebook Groups هدف ربط، لذا يعيد network: "fbg" الرمز code: 508 عند إنشاء الجلسة.أما WhatsApp فمتاح في الوضع المباشر. يفتح Embedded Signup من Meta في النافذة المنبثقة، وأحداث النتيجة هي نفسها كأي شبكة أخرى.

التطبيقات الأصلية

يفتح التطبيق الأصلي url نفسه، في متصفح النظام، ويعرف النتيجة باستطلاع الحصول على Link Session. عيّن origin على مخططك المخصص (myapp://connected) حتى يكون للصفحة طريق عودة إلى تطبيقك؛ المخطط المخصص لا يمكنه تلقّي الأحداث، لأنه لا توجد نافذة متصفح تُرسل إليها.
  • iOS — ‏ASWebAuthenticationSession، أو SFSafariViewController.
  • Android — ‏Chrome Custom Tabs.
لا تفتح رابط ربط أبدًا في webview مضمّن (WKWebView أو UIWebView أو WebView في Android). ترفض الشبكات الاجتماعية المصادقة فيه: يرفض Google تسجيل الدخول بالخطأ disallowed_useragent، وتحجبه Meta كليًا. يرى مستخدمك صفحة الخطأ الخاصة بالشبكة نفسها، لا صفحتنا، ولا شيء يمكنك تغييره من جانبك يصلح ذلك. مكوّنات متصفح النظام أعلاه موجودة لهذا السبب بالضبط وتُبقي المستخدم داخل تطبيقك.

ما يتطلبه الوضع المباشر

  • Max Pack. إنشاء جلسة بوضع connect من دونه يعيد code: 504، أيًّا كان ما يقوله الطلب غير ذلك.
  • origin على كل جلسة. لا توجد قائمة سماح ولا خطوة تسجيل — ترسله مع كل استدعاء. حذفه يعيد code: 505؛ والقيمة التي ليست أصل https أو مخططًا مخصصًا أو http://localhost تعيد code: 506.
  • network فعّلها حسابك. الاسم غير المعروف يعيد code: 508؛ والاسم المعروف الذي لم يفعّله حسابك يعيد code: 509، وهو ما يمكنك إصلاحه في صفحة Social Networks.
  • ليس allowedSocial. لا يمكن جمعه مع network (يعيد code: 507) — فجلسة الشبكة الواحدة هي قائمة السماح الخاصة بها بالفعل.
كل واحد من هذه الرموز موجود في مرجع أخطاء Link Session، مع الرسالة التي تعيدها API.

الخطوات التالية

Link Completion Events

كل حدث ترسله النافذة المنبثقة، والمستمع الذي يتلقاها.

ذات صلة

Create a Link Session

معاملات mode وorigin وnetwork، وأشكال الاستجابة.

Get a Link Session

استطلع الاكتمال عندما يتعذر عليك استخدام نافذة منبثقة.