تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

المراسلة الأصلية

يمكن للإضافات تبادل الرسائل مع التطبيقات الأصلية باستخدام واجهة برمجة تطبيقات مشابهة لواجهات برمجة التطبيقات الأخرى الخاصة بتمرير الرسائل. يجب أن تسجّل التطبيقات الأصلية التي تتوافق مع هذه الميزة مضيف المراسلة مع التطبيقات الأصلية يمكنه التواصل مع الإضافة. يبدأ Chrome المضيف في عملية منفصلة ويتواصل معه باستخدام تدفقات الإدخال والإخراج العادية.

مضيف المراسلة مع التطبيقات الأصلية

لتسجيل مضيف المراسلة مع التطبيقات الأصلية، يجب أن يحفظ التطبيق ملفًا يحدّد إعدادات مضيف المراسلة مع التطبيقات الأصلية.

في ما يلي مثال على الملف:

{
  "name": "com.my_company.my_application",
  "description": "My Application",
  "path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"]
}

يجب أن يكون ملف بيان مضيف المراسلة مع التطبيقات الأصلية بتنسيق JSON صالحًا وأن يحتوي على الحقول التالية:

name: اسم مضيف المراسلة مع التطبيقات الأصلية ترسل التطبيقات هذه السلسلة إلى runtime.connectNative() أو runtime.sendNativeMessage(). يمكن أن يحتوي هذا الاسم على أحرف أبجدية رقمية صغيرة وشرطات سفلية ونقاط فقط. لا يمكن أن يبدأ الاسم أو ينتهي بنقطة، ولا يمكن أن تتبع النقطة نقطة أخرى.
description: وصف موجز للتطبيق
path: مسار الملف الثنائي لمضيف المراسلة مع التطبيقات الأصلية: على نظامَي التشغيل Linux وmacOS، يجب أن يكون المسار مطلقًا. في نظام التشغيل Windows، يمكن أن يكون المسار نسبيًا بالنسبة إلى الدليل الذي يحتوي على ملف البيان. يتم بدء عملية المضيف مع ضبط الدليل الحالي على الدليل الذي يحتوي على ملف المضيف الثنائي. على سبيل المثال، إذا تم ضبط هذه المَعلمة على C:\Application\nm_host.exe، سيتم بدء تشغيلها باستخدام الدليل الحالي C:\Application.
type: نوع الواجهة المستخدَمة للتواصل مع مضيف المراسلة مع التطبيقات الأصلية. تتضمّن هذه المَعلمة قيمة محتملة واحدة: stdio. يشير ذلك إلى أنّ Chrome يجب أن يستخدم stdin وstdout للتواصل مع المضيف.
allowed_origins: قائمة بالإضافات التي يجب أن يكون لديها إذن الوصول إلى مضيف المراسلة مع التطبيقات الأصلية. لا يمكن أن تحتوي قيم allowed_origins على أحرف بدل.

موقع مضيف المراسلة مع التطبيقات الأصلية

يعتمد مكان ملف البيان على النظام الأساسي.

على Windows، يمكن العثور على ملف البيان في أي مكان في نظام الملفات. يجب أن ينشئ مثبِّت التطبيق مفتاح تسجيل، إما HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application أو HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application، وأن يضبط القيمة التلقائية لهذا المفتاح على المسار الكامل إلى ملف البيان. على سبيل المثال، باستخدام الأمر التالي:

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

أو باستخدام ملف .reg التالي:

Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"

عندما يبحث Chrome عن مضيفي المراسلة الأصلية، يتم أولاً طلب البحث في سجل 32 بت، ثم في سجل 64 بت.

على نظامَي التشغيل macOS وLinux، يختلف موقع ملف البيان الخاص بمضيف المراسلة الأصلية حسب المتصفّح (Google Chrome أو Google Chrome for Testing أو Chromium). يتم البحث عن مضيفي المراسلة الأصلية على مستوى النظام في موقع ثابت، بينما يتم البحث عن مضيفي المراسلة الأصلية على مستوى المستخدم في الدليل الفرعي NativeMessagingHosts/ ضمن دليل الملف الشخصي للمستخدم.

‫macOS (على مستوى النظام): Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: /Library/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: /Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
‫macOS (مسار تلقائي خاص بالمستخدم): Google Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: ~/Library/Application Support/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json
‫Linux (على مستوى النظام): Google Chrome: /etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json; Google Chrome for Testing: /etc/opt/chrome_for_testing/native-messaging-hosts/com.my_company.my_application.json; Chromium: /etc/chromium/native-messaging-hosts/com.my_company.my_application.json
‫Linux (خاص بالمستخدم، المسار الافتراضي): Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: ~/.config/google-chrome-for-testing/NativeMessagingHosts/com.my_company.my_application.json; Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

بروتوكول المراسلة الأصلية

يبدأ Chrome كل مضيف المراسلة مع التطبيقات الأصلية في عملية منفصلة ويتواصل معه باستخدام الإدخال المعياري (stdin) والإخراج المعياري (stdout). ويتم استخدام التنسيق نفسه لإرسال الرسائل في كلا الاتجاهين، ويتم نشر كل رسالة على نحو متسلسِل باستخدام JSON، ويتم ترميزها باستخدام UTF-8، ويسبقها طول الرسالة البالغ 32 بت بترتيب البايت الأصلي. الحد الأقصى لحجم رسالة واحدة من مضيف المراسلة الأصلية هو 1 ميغابايت، وذلك بشكل أساسي لحماية Chrome من التطبيقات الأصلية التي لا تعمل بشكل سليم. يبلغ الحد الأقصى لحجم الرسالة المُرسَلة إلى مضيف المراسلة مع التطبيقات الأصلية 64 ميغابايت.

الوسيطة الأولى لمضيف المراسلة مع التطبيقات الأصلية هي مصدر المتصل، ويكون عادةً chrome-extension://[ID of allowed extension]. يتيح ذلك لمضيفي المراسلة مع التطبيقات الأصلية تحديد مصدر الرسالة عند تحديد عدة إضافات في المفتاح allowed_origins في بيان مضيف المراسلة مع التطبيقات الأصلية.

في نظام التشغيل Windows، يتم أيضًا تمرير وسيطة سطر أوامر إلى مضيف المراسلة مع التطبيقات الأصلية تتضمّن معرّفًا لنافذة Chrome الأصلية التي يتم استدعاؤها: --parent-window=<decimal handle value>. يتيح ذلك لمضيف المراسلة مع التطبيقات الأصلية إنشاء نوافذ واجهة مستخدم أصلية مرتبطة بشكل صحيح. يُرجى العِلم أنّ هذه القيمة ستكون 0 إذا كان سياق الاتصال هو عامل خدمة.

عند إنشاء منفذ مراسلة باستخدام runtime.connectNative()، يبدأ Chrome عملية مضيف مراسلة أصلية ويستمر في تشغيلها إلى أن يتم إيقاف المنفذ. من ناحية أخرى، عند إرسال رسالة باستخدام runtime.sendNativeMessage() بدون إنشاء منفذ مراسلة، يبدأ Chrome عملية جديدة لمضيف المراسلة مع التطبيقات الأصلية لكل رسالة. في هذه الحالة، يتم التعامل مع الرسالة الأولى التي أنشأتها عملية المضيف على أنّها ردّ على الطلب الأصلي، وسينقلها Chrome إلى دالة معاودة الاتصال الخاصة بالردّ المحدّدة عند استدعاء runtime.sendNativeMessage(). ويتم تجاهل جميع الرسائل الأخرى التي ينشئها مضيف المراسلة مع التطبيقات الأصلية في هذه الحالة.

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

إنّ إرسال الرسائل واستلامها من تطبيق أصلي يشبه إلى حد كبير عملية تبادل الرسائل بين الإضافات. والفرق الرئيسي هو استخدام runtime.connectNative() بدلاً من runtime.connect()، واستخدام runtime.sendNativeMessage() بدلاً من runtime.sendMessage().

لاستخدام هذه الطرق، يجب تحديد إذن "nativeMessaging" في ملف بيان الإضافة.

لا تتوفّر هذه الطرق داخل نصوص البرامج الخاصة بالمحتوى، بل داخل صفحات الإضافة ومشغّل الخدمات فقط. للتواصل من نص برمجي خاص بالمحتوى إلى التطبيق الأصلي، أرسِل الرسالة إلى عامل الخدمة لتمريرها إلى التطبيق الأصلي.

ينشئ المثال التالي عنصر runtime.Port مرتبطًا بمضيف المراسلة مع التطبيقات الأصلية com.my_company.my_application، ويبدأ في الاستماع إلى الرسائل الواردة من هذا المنفذ، ويرسل رسالة صادرة واحدة:

const port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener((msg) => {
  console.log('Received', msg);
});
port.onDisconnect.addListener(() => {
  if (chrome.runtime.lastError) {
    console.error(
      'Disconnected due to error:',
      chrome.runtime.lastError.message
    );
  } else {
    console.log('Disconnected');
  }
});
port.postMessage({text: 'Hello, my_application'});

استخدِم runtime.sendNativeMessage لإرسال رسالة إلى التطبيق الأصلي بدون إنشاء منفذ، مثلاً:

chrome.runtime.sendNativeMessage(
  'com.my_company.my_application',
  {text: 'Hello'},
  (response) => {
    if (chrome.runtime.lastError) {
      console.error(
        'Error sending native message:',
        chrome.runtime.lastError.message
      );
      return;
    }
    console.log('Received', response);
  }
);

تصحيح أخطاء المراسلة الأصلية

عند حدوث أخطاء في المراسلة الأصلية، تتم كتابة ناتج التشخيص في سجلّ أخطاء Chrome.

‫Linux وmacOS

# Linux
google-chrome --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

Windows

شغِّل Chrome مع تفعيل التسجيل:

chrome.exe --enable-logging --log-level=1

أدخِل --user-data-dir="%TEMP%\nm-debug" لتشغيل مثيل منفصل بدون ربطه بعملية Chrome حالية.

لعرض الناتج، استخدِم الأمر chrome_debug.log من خلال PowerShell:

$log = "$env:LOCALAPPDATA\Google\Chrome\User Data\chrome_debug.log"
Get-Content -Wait $log | Select-String "native_messag|launch_context"

يمكنك أيضًا فتح chrome_debug.log في محرر نصوص والبحث عن launch_context.cc أو native_message_process_host.cc.

تفاصيل تسجيل المفاتيح

يتم تسجيل حالات تعذُّر البحث عن ملف البيان وتحليله في launch_context.cc كتحذيرات. استخدِم --log-level=1 بدلاً من 2 (ERROR)، ما يؤدي إلى إيقاف بيانات التشخيص هذه عند بدء التشغيل.
ابحث عن launch_context للعثور على أخطاء تشغيل ملف البيان والملف الثنائي، وعن native_messag للعثور على أخطاء حجم الحمولة وأخطاء الاتصال عبر الأنابيب.

الأخطاء الشائعة

في ما يلي بعض الأخطاء الشائعة ونصائح لحلّها:

تعذّر بدء مضيف المراسلة مع التطبيقات الأصلية.

تحقَّق مما إذا كانت لديك أذونات كافية لتنفيذ ملف مضيف المراسلة مع التطبيقات الأصلية.

تم تحديد اسم مضيف المراسلة مع التطبيقات الأصلية غير صالح.

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

خرج المضيف الأصلي.

تم إيقاف قناة الاتصال بمضيف المراسلة مع التطبيقات الأصلية قبل أن يقرأ Chrome الرسالة. من المرجّح أن يكون مصدر هذا الطلب هو مضيف المراسلة مع التطبيقات الأصلية.

لم يتم العثور على مضيف المراسلة مع التطبيقات الأصلية المحدّد.

تحقق مما يلي:

هل تمت تهجئة الاسم بشكل صحيح في الإضافة وفي ملف البيان؟
في نظام التشغيل Windows، هل يتوفّر مفتاح التسجيل ضمن HKEY_CURRENT_USER أو HKEY_LOCAL_MACHINE، وهل تشير قيمته التلقائية إلى مسار البيان الكامل؟ يطلب Chrome عرض سجلّ 32 بت أولاً، ثم عرض سجلّ 64 بت. استخدِم regedit لتأكيد المفتاح. اطّلِع على موقع مضيف المراسلة مع التطبيقات الأصلية.
على نظامَي التشغيل macOS وLinux، هل يقع ملف البيان في الدليل المتوقّع ويحمل اسم المضيف (مثل com.my_company.my_application.json)؟ راجِع موقع مضيف المراسلة مع التطبيقات الأصلية.
هل ملف البيان بالتنسيق الصحيح؟ على وجه الخصوص، هل ملف JSON صالح ومنسّق بشكل سليم وهل تتطابق القيم مع تعريف بيان مضيف المراسلة مع التطبيقات الأصلية؟
هل الملف المحدّد في path متوفّر؟ على نظام التشغيل Windows، قد تكون المسارات نسبية، ولكن على نظامَي التشغيل macOS وLinux، يجب أن تكون المسارات مطلقة.

لا يمكن الوصول إلى مضيف المراسلة مع التطبيقات الأصلية المحدّد.

هل تم إدراج مصدر الإضافة في allowed_origins؟

حدث خطأ أثناء التواصل مع مضيف المراسلة مع التطبيقات الأصلية.

يشير ذلك إلى تنفيذ غير صحيح لبروتوكول الاتصال في مضيف المراسلة مع التطبيقات الأصلية.

تأكَّد من أنّ جميع النتائج في stdout تتوافق مع بروتوكول الرسائل الأصلية. إذا أردت طباعة بعض البيانات لأغراض تصحيح الأخطاء، يُرجى التواصل مع stderr.
تأكَّد من أنّ طول الرسالة المكوّن من 32 بت بتنسيق العدد الصحيح الأصلي للنظام الأساسي (little-endian / big-endian).
يجب ألا يتجاوز طول الرسالة 1024*1024.
يجب أن يكون حجم الرسالة مساويًا لعدد وحدات البايت في الرسالة. وقد يختلف ذلك عن "طول" السلسلة، لأنّ الأحرف قد يتم تمثيلها بعدّة وحدات بايت.
على أجهزة Windows فقط: تأكَّد من ضبط وضع الإدخال/الإخراج للبرنامج على O_BINARY. يكون وضع الإدخال/الإخراج تلقائيًا O_TEXT، ما يؤدي إلى تلف تنسيق الرسالة لأنّه يتم استبدال فواصل الأسطر (\n = 0A) بنهايات أسطر بنمط Windows (\r\n = 0D 0A). يمكن ضبط وضع الإدخال/الإخراج باستخدام __setmode.