Skip to main content
عندما تفتح صفحة ربط في نافذة منبثقة، تستطيع صفحتك أنت الاستماع إلى ما يقع فيها: ربط مستخدمك Reddit، أو تراجعه، أو فشل الربط. تحصل على حدث لكل نتيجة، فتتحدث واجهتك لحظة وقوع الأمر لا وفق مؤقّت. عيّن origin عند إنشاء الرابط، وافتح url المُعاد في نافذة منبثقة، واستمع. لا شيء آخر مطلوب، ولا شيء يتغير للروابط المُنشأة دون origin — فهي تتصرف تمامًا كما كانت دائمًا.
تستخدم الأداة المضمّنة؟ هذا مُهيّأ لك بالفعل. يتلقى السكربت هذه الأحداث ويسلّمها إلى connect.on("success", …) بعد نزع البادئة connect: — دون مستمع message، ولا فحص أصل، ولا استطلاع popup.closed تكتبه. هذه الصفحة هي بروتوكول السلك الكامن تحت ذلك، وما تبني عليه عندما تملك أنت النافذة: الوضع المباشر، أو نافذة منبثقة تفتحها بنفسك.
تُرسل الأحداث فقط إلى origin الفعلي الذي عيّنته على الرابط، وفقط إلى النافذة التي فتحت النافذة المنبثقة. تحقق دائمًا من event.origin في مستمعك مع ذلك: يمكن لأي صفحة إرسال رسالة إلى نافذتك، والأصل هو الجزء الوحيد من الرسالة الذي لا يمكن تزويره.

الأحداث

كل رسالة تُرسل إلى صفحتك هي كائن على شكل { source: "ayrshare", version: 1, event, ... }، ويحمل network كلما كان الحدث يخص شبكة. حدثان لا يحملانها: connect:closed القادم من صفحة الربط المستضافة، حيث يعني أن مستخدمك ضغط على Done لا أن عملية ربط واحدة انتهت، وconnect:ready الخاص بالأداة (انظر أدناه). أما النتائج التي تُركّبها شيفرتك بنفسها — نافذة منبثقة محجوبة، أو نافذة أغلقها مستخدمك — فلا تأتي منا ولا تحمل إلا ما تعطيه لها.
تختلف الأداة المضمّنة في حدث واحد. فحدث ready لديها يعلن أن فتحة أصبحت جاهزة لا شيئًا عن شبكة، لذا لا يحمل network — بينما ready الخاص بالنافذة المنبثقة يُسمّي الشبكة التي فُتحت من أجلها. إذا كنت تعالج السطحين من مستمع واحد، فاقرأ network بحذر على ready.تضيف الأداة أيضًا سبب cancelled واحدًا لا يرسله هذا السطح أبدًا: superseded، عندما يحل استدعاء popup() ثانٍ محل محاولة لا تزال جارية. هنا توجد نافذة واحدة ونتيجة واحدة، فلا شيء يُستبدل.
يصل واحد بالضبط من connect:success أو connect:error أو connect:cancelled لكل عملية ربط. أما connect:closed فليس واحدًا منها — بل يتبعها، ليخبرك بأن النافذة المنبثقة أُغلقت عن قصد. لا يُرسل connect:success إلا بعد حفظ الحساب، لذا فإن استدعاء GET /user بعده مباشرةً يُظهر الحساب المتصل بالفعل.
تبقى النافذة المنبثقة مفتوحة بعد connect:error حتى يتمكن مستخدمك من قراءة ما حدث من خطأ. وتُغلق نفسها بعد connect:success وconnect:cancelled. أضف &autoClose=false إلى عنوان URL لإبقائها مفتوحة في كل الحالات أثناء التصحيح.

الاستماع

أمران يفعلهما هذا المقتطف يسهل إغفالهما. فهو يتحقق من event.origin، ويراقب النافذة المنبثقة التي أغلقها مستخدمك يدويًا — فالنافذة المغلقة لا تستطيع إرسال أي شيء، والاستطلاع هو السبيل الوحيد لملاحظة ذلك.

الأخطاء

يحمل connect:error الرموز نفسها التي تحملها بقية API، فالرمز الذي تراه هنا يعني ما يعنيه في كل مكان آخر. الرمز الخاص بهذا السطح وحده: أي شيء آخر هو فشل الشبكة الاجتماعية نفسها، يُبلَّغ عنه بالرمز الذي يحمله ذلك الفشل أصلًا — مثل 322 لمشكلة تفويض في Instagram، وهو ما يشمل حسابًا لا يزال شخصيًا (Personal) بدلًا من احترافي (Professional).

الرابط الميت يصل بطريقة مختلفة

الرابط المنتهي الصلاحية أو المُبطل أو المجهول يُرفض قبل أن تتمكن الصفحة من معرفة وجهة إرسال الأحداث، فلا يستطيع إرسال أي حدث. يرى مستخدمك السبب ورمزه على الشاشة، وتسمع صفحتك connect:cancelled عندما يغلق النافذة. للتمييز بينها، استطلع الحصول على Link Session: فهو يبلّغ عن expired وrevoked بشكل موثوق، ويعيد 502 للرابط غير الموجود.

إذا كنت تفضّل عدم إدارة نافذة منبثقة

خياران، والثاني وحده يتخلى عن الأحداث. دع الأداة تملك النافذة. تفتح الأداة المضمّنة النافذة وتراقبها نيابةً عنك وتسلّم كل حدث أعلاه إلى معالجاتك. لا تزال تحصل على success لحظة حفظ الحساب؛ أنت فقط لا تكتب التمديدات. كما أن إطاراتها تعني أن معظم الشبكات لا تفتح نافذة منبثقة إطلاقًا حتى تسجيل دخول الشبكة نفسها. استطلع بدلًا من ذلك. إذا كانت النافذة المنبثقة غير متاحة فعلًا — تطبيق يُعرض من الخادم، أو تطبيق محمول يفتح الرابط في متصفح النظام — فاستطلع الحصول على Link Session. فهو يبلّغ عن completedAt وcompletedNetworks بمجرد حفظ الحساب، وهي اللحظة نفسها التي كان connect:success سيُرسل فيها. يكتمل Telegram دائمًا بهذه الطريقة، لأنه يكتمل خارج النطاق دون أي استدعاء متصفح راجع.