إصدار Digital Credentials API في Chrome 155

Natalia Markoborodova

تاريخ النشر: 23 أكتوبر 2026

في الإصدار 155 من Chrome والإصدارات الأحدث، يتم تفعيل إصدار Digital Credentials API تلقائيًا، لذا لن تحتاج بعد الآن إلى رمز مميّز أو علامة مرحلة التجربة والتقييم لاستخدامه. ‫Digital Credentials API هي طبقة نقل تتيح للمواقع الإلكترونية الاتصال بتطبيقات المحفظة المثبَّتة على جهاز المستخدم الجوّال. من خلال ميزة "الإصدار"، يمكن لجهات الإصدار إضافة بيانات اعتماد جديدة (مثل مستندات التعريف الرقمية) مباشرةً إلى تطبيق المحفظة الخاص بالمستخدم.

خلفية

يتألف منظومة الهوية الرقمية من ثلاثة أطراف: جهات الإصدار وجهات التحقّق (تُعرف أيضًا باسم الأطراف المعتمِدة) وحاملي الهوية (تطبيقات المحفظة). غالبًا ما يضيف المستخدمون مستند تعريف رقميًا إلى تطبيق المحفظة من خلال إضافة بطاقة الدفع مباشرةً، حيث يبدأ المستخدم عملية الإصدار من الموقع الإلكتروني أو التطبيق الخاص بجهة الإصدار. على سبيل المثال، يمكن لطالب على الموقع الإلكتروني الخاص بجامعته (جهة الإصدار) حفظ بطاقة جامعية رقمية في تطبيق المحفظة المفضّل لديه (حامل البطاقة).

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

طريقة إصدار بيانات الاعتماد الرقمية

لتبسيط هذه العملية، يتيح Chrome إصدار بيانات الاعتماد باستخدام واجهة برمجة التطبيقات Digital Credentials API من W3C. تُضاف هذه الميزة إلى إمكانات العرض (مشاركة البيانات المطلوبة والمحدّدة من بيانات اعتماد رقمية مع جهة التحقّق)، والتي تم طرحها في الإصدار 141 من Chrome. عندما يطلب موقع إلكتروني لجهة إصدار navigator.credentials.create() مع عضو digital يحتوي على طلب إصدار، يمرّر Chrome الطلب إلى نظام التشغيل (على Android، "إدارة بيانات الاعتماد"). يعرض نظام التشغيل بعد ذلك واجهته الخاصة حيث يختار المستخدم تطبيق محفظة. تعمل واجهة برمجة التطبيقات مع البروتوكولات المتّبعة في المجال، مثل OpenID لإصدار بيانات الاعتماد القابلة للتحقّق (OpenID4VCI). تتيح عملية الإصدار مسارَين: مسار على الجهاز نفسه على Android، ومسار على أجهزة متعددة يبدأ على الكمبيوتر المكتبي وينتهي على جهاز Android.

عملية الربط على جهاز Android نفسه

على أجهزة Android، يمرّر Chrome طلب الإصدار إلى Credential Manager في Android، والتي تعرض قائمة بتطبيقات المحفظة المتوافقة على الجهاز. يختار المستخدم محفظة ويوافق على إضافة بيانات الاعتماد. بعد ذلك، يحصل تطبيق المحفظة على بيانات الاعتماد من جهة الإصدار باستخدام بروتوكول الإصدار، مثل OpenID4VCI.

مسار الإجراءات على أجهزة متعددة على الكمبيوتر المكتبي

على الكمبيوتر المكتبي، يعرض Chrome رمز استجابة سريعة. يمسح المستخدم الرمز ضوئيًا باستخدام جهاز Android ويكمل العملية على ذلك الجهاز، كما هو موضّح في القسم السابق. تستخدم الأجهزة البلوتوث للتأكّد من أنّها قريبة من بعضها، لذا يطلب Chrome من المستخدم تفعيل البلوتوث إذا كان غير مفعّل. يستخدم Chrome آلية العمل نفسها على جميع الأجهزة لعرض Digital Credentials API.

تنفيذ عملية الإصدار باستخدام واجهة برمجة التطبيقات

لبدء عملية الإصدار، يمكنك استدعاء navigator.credentials.create() وتمرير طلبات الإصدار داخل عضو digital. يجب إجراء هذا الطلب من معالج نقرات أو معالج إجراءات تفاعلية آخر من المستخدم، لأنّ الطلب يتطلّب تفعيلاً عابرًا من المستخدم. يستخدم المثال التالي عرض بيانات اعتماد OpenID4VCI مع مسار الرمز المفوَّض مسبقًا:

// Call this function from a user gesture handler, for example, a button's
// click handler. The pre-authorized code is a short-lived, single-use code
// that your server generates for the signed-in user.
async function issueDigitalCredential(preAuthorizedCode) {
  // Check for Digital Credentials API and protocol support.
  if (!window.DigitalCredential ||
      !DigitalCredential.userAgentAllowsProtocol('openid4vci-v1')) {
    // Provide an alternative issuance method.
    showAlternativeIssuanceFlow();
    return;
  }

  // Construct a credential offer according to the OpenID4VCI
  // specification. This example uses the format that the
  // demo CMWallet supports.
  const credentialOffer = {
    credential_issuer: 'https://issuer.example',
    credential_configuration_ids: ['org.iso.18013.5.1.mDL'],
    grants: {
      'urn:ietf:params:oauth:grant-type:pre-authorized_code': {
        'pre-authorized_code': preAuthorizedCode
      }
    },
    // Metadata that the wallet uses to request and display the credential.
    credential_issuer_metadata: {
      credential_issuer: 'https://issuer.example',
      credential_endpoint: 'https://issuer.example/openid4vci/credential',
      nonce_endpoint: 'https://issuer.example/openid4vci/nonce',
      credential_configurations_supported: {
        'org.iso.18013.5.1.mDL': {
          format: 'mso_mdoc',
          doctype: 'org.iso.18013.5.1.mDL',
          // Bind the credential to a key that the wallet generates.
          cryptographic_binding_methods_supported: ['cose_key'],
          proof_types_supported: {
            jwt: { proof_signing_alg_values_supported: ['ES256'] }
          },
          credential_metadata: {
            display: [{ name: 'Mobile driving license', locale: 'en-US' }],
            // The claims that this credential contains. For a full list of
            // standard mDL claims, see the ISO/IEC 18013-5 specification.
            claims: [{
              path: ['org.iso.18013.5.1', 'family_name'],
              display: [{ name: 'Family name', locale: 'en-US' }]
            }
            // ... Add any other claims for your credential here.
            ]
          }
        }
      }
    },
    // Metadata of the authorization server that issues access tokens.
    authorization_server_metadata: {
      issuer: 'https://issuer.example',
      token_endpoint: 'https://issuer.example/openid4vci/token'
    }
  };

  try {
    const credential = await navigator.credentials.create({
      digital: {
        requests: [{
          // The protocol identifier for OpenID4VCI 1.0.
          protocol: 'openid4vci-v1',
          // Pass the offer as an object, not as a JSON string.
          data: credentialOffer
        }]
      }
    });

    // The wallet handled the request. credential.data is an object that
    // contains the wallet's protocol-specific response. It is not the issued
    // credential, and it does not necessarily mean that issuance is complete.
    // Your server knows when the wallet retrieves the credential from your
    // credential endpoint.
    // Implement your custom logic here as needed.
    showIssuanceStatus(credential);
  } catch (error) {
    switch (error.name) {
      case 'NotAllowedError':
        // The user canceled the flow, no wallet can handle the request, or
        // the call does not have transient user activation.
        break;
      case 'NotSupportedError':
        // The browser does not support Digital Credentials API issuance.
        // Fall back to your custom alternative flow logic.
        showAlternativeIssuanceFlow();
        break;
      case 'TypeError':
        // The request is malformed, for example, data is not an object.
        console.error('Invalid issuance request:', error);
        break;
      default:
        // For example, AbortError or NetworkError.
        console.error('Credential issuance failed:', error);
    }
  }
}

const addButton = document.querySelector('#add-to-wallet');
addButton.addEventListener('click', () => {
  // Your server adds a pre-authorized code for the signed-in user
  // to the button's data-pre-authorized-code attribute.
  issueDigitalCredential(addButton.dataset.preAuthorizedCode);
});

في هذا المثال، يمثّل showAlternativeIssuanceFlow() وshowIssuanceStatus() طريقة عمل تطبيقك.

لاستدعاء create() من إطار iframe متعدّد المصادر، يجب أن تسمح الصفحة المضمّنة بميزة سياسة الأذونات digital-credentials-create. بخلاف ذلك، يتم رفض الطلب مع ظهور الخطأ NotAllowedError:

<iframe src="https://issuer.example" allow="digital-credentials-create">
</iframe>

التغييرات التي تم إجراؤها منذ مرحلة التجربة والتقييم

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

تم استهلاك تفاعل المستخدم

اعتبارًا من الإصدار 146 من Chrome، يؤدي طلب create() مع عضو digital إلى استهلاك تفعيل المستخدم المؤقت، كما تتطلّب المواصفات. خلال مرحلة التجربة والتقييم، تحقّق Chrome من تفعيل المستخدمين، ولكنّه لم يستهلكه.

نتيجةً لذلك، يحتاج كل طلب create() إلى إجراء تفاعلي من المستخدم، مثل النقر على زر. بدون تفعيل المستخدم، يتم رفض الوعد باستخدام NotAllowedError. بعد المكالمة، لا يمكن لواجهة برمجة التطبيقات window.open() وواجهات برمجة التطبيقات الأخرى التي تتطلّب تفعيل المستخدم استخدام الإيماءة نفسها.

عمليات رفض الإلغاء باستخدام "NotAllowedError"

بدءًا من الإصدار 148 من Chrome، يتم رفض الوعد الذي يعرضه create() مع ظهور NotAllowedError عندما يلغي المستخدم العملية، على سبيل المثال، من خلال إغلاق أداة اختيار المحفظة على Android أو إغلاق مربّع حوار رمز الاستجابة السريعة على الكمبيوتر المكتبي. يتم أيضًا رفض الوعد من خلال NotAllowedError عندما لا يتمكّن أي تطبيق محفظة من معالجة الطلب. خلال مرحلة التجربة والتقييم، تم رفض هذه الحالات باستخدام NetworkError.

إذا كان الرمز البرمجي يتحقّق من NetworkError لرصد الإلغاء، يجب تعديله للتحقّق من NotAllowedError بدلاً من ذلك.

تؤدي معرّفات البروتوكولات غير المعروفة إلى ظهور تحذير

تحدّد المواصفات معرّفًا واحدًا لبروتوكول الإصدار، وهو openid4vci-v1، للإصدار 1.0 من OpenID4VCI. يتعرّف الإصدار 155 من Chrome على openid4vci-v1، وكذلك openid4vci. بما أنّ السمة openid4vci ليست جزءًا من المواصفات، ننصحك باستخدام السمة openid4vci-v1.

يمرّر Chrome الطلبات التي تتضمّن أي معرّف بروتوكول إلى المنصة. ومع ذلك، اعتبارًا من الإصدار 151 من Chrome، تعرض "أدوات مطوّري البرامج" تحذيرًا بشأن الإيقاف النهائي عندما تطلب صفحة create() باستخدام معرّف بروتوكول غير معروف. يهدف Chrome إلى حظر الطلبات التي تتضمّن معرّفات بروتوكولات غير معروفة. لمعرفة الحالة، يُرجى الاطّلاع على إدخال فلترة البروتوكول بشكل أكثر تحديدًا في Digital Credential API.

لاختبار هذا السلوك، فعِّل chrome://flags/#enable-experimental-web-platform-features. عند تفعيل هذه العلامة، يتجاهل create() الطلبات التي تتضمّن معرّفات بروتوكول غير معروفة ويرفضها مع عرض الرمز TypeError في حال عدم توفّر أي طلبات أخرى. بالإضافة إلى ذلك، تعرض الدالة DigitalCredential.userAgentAllowsProtocol() القيمة true للبروتوكولات المعروفة فقط. بدون العلامة، تتحقّق الدالة فقط من أنّ المعرّف مكتوب بشكل صحيح. لذلك، لا تعتمد على userAgentAllowsProtocol() وحده لرصد الميزات. يُرجى التعامل مع NotSupportedError كما هو موضّح في المثال.

المصادر المبهمة محظورة

اعتبارًا من الإصدار 151 من Chrome، يرفض create() استخدام NotAllowedError عندما يستدعيه مستند يتضمّن مصدرًا مبهمًا، مثل إطار iframe في وضع الحماية بدون الرمز المميّز allow-same-origin. خلال مرحلة التجربة والتقييم، لم يحظر Chrome هذه الطلبات.

الاختبار باستخدام محفظة افتراضية

اعتبارًا من الإصدار Chrome 152، يمكنك اختبار عملية الإصدار بدون جهاز Android أو تطبيق محفظة. ينفّذ الأمر التجريبي DigitalCredentials.setVirtualWalletBehavior في بروتوكول أدوات مطوّري البرامج في Chrome (CDP) المحفظة الافتراضية التي تحدّدها المواصفات للاختبار الآلي. يمكن للمحفظة الافتراضية الردّ بالبيانات التي تقدّمها أو رفض الطلبات كما لو أنّ المستخدم ألغى العملية أو ترك الطلبات في انتظار المراجعة لاختبار المهلات وعمليات الإلغاء.

يضبط اختبار Puppeteer التالي المحفظة الافتراضية للاستجابة لطلبات openid4vci-v1، ثم ينقر على الزر الذي يبدأ عملية الإصدار:

const client = await page.createCDPSession();
await client.send('DigitalCredentials.setVirtualWalletBehavior', {
  action: 'respond',
  protocol: 'openid4vci-v1',
  response: {}
});

// Clicking the button provides the user activation that create() requires.
await page.click('#add-to-wallet');

الاعتماد في المجال

نلاحظ تزايدًا في استخدام Digital Credentials API لإصدار بيانات الاعتماد. على سبيل المثال، تستخدم المؤسسة المالية الألمانية Sparkasse واجهة برمجة التطبيقات Digital Credentials API للسماح لأصحاب الحسابات بحفظ بيانات اعتماد العمر التي تم التحقّق منها في "محفظة Google". ويمكن لأصحاب الحسابات بعد ذلك استخدام بيانات الاعتماد هذه لإثبات أعمارهم على الإنترنت وشخصيًا.

للتجربة:

قبل اختبار إصدار Digital Credentials API، تأكَّد من توفّر ما يلي:

• يُرجى التحديث إلى الإصدار 155 من Chrome أو إصدار أحدث.
• ثبِّت تطبيق محفظة متوافقًا على جهاز Android، مثل الإصدار التجريبي من CMWallet.
• تفعيل البلوتوث على كلا الجهازين (مسار العمل على عدة أجهزة فقط)

لاختبار مسار العمل على عدة أجهزة:

1. على الكمبيوتر، افتح الموقع الإلكتروني التجريبي لجهة الإصدار.
2. انقر على الزر إضافة.
3. امسح رمز الاستجابة السريعة ضوئيًا باستخدام جهاز Android واتّبِع التعليمات الظاهرة على الشاشة.

لاختبار عملية استخدام الجهاز نفسه، افتح الموقع الإلكتروني التجريبي لجهة الإصدار في Chrome على جهاز Android.

موارد المطوِّرين

لبدء دمج إصدار Digital Credentials API في موقعك الإلكتروني، استخدِم المراجع التالية:

• يمكنك الاطّلاع على دليل المطوّر الذي أعدّته مجموعة Web Identity & Credentials Adoption Community Group التابعة لاتحاد W3C.
• اطّلِع على مواصفات بيانات الاعتماد الرقمية من W3C.
• اطّلِع على مواصفات OpenID لإصدار بيانات الاعتماد القابلة للتحقّق 1.0.
• يمكنك استكشاف الرمز المصدر للتطبيق التجريبي CMWallet، وهو تطبيق تجريبي مفتوح المصدر للمحفظة على Android.
• تعرَّف على كيفية تعامل تطبيقات المحفظة على Android مع طلبات الإصدار من Credential Manager.
• جرِّب الموقع الإلكتروني التجريبي لجهة الإصدار مع تطبيق CMWallet التجريبي المثبَّت على جهاز Android.
• يمكنك استكشاف الإصدار التجريبي من أداة إنشاء طلبات "بيانات الاعتماد الرقمية" لمعرفة شكل حمولة الطلب.

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

للإبلاغ عن خطأ أو طلب ميزة، يمكنك تقديم طلب في أداة تتبُّع الأخطاء في Chromium.