إنشاء معاملات للاشتراك الرقمي

يوضّح هذا الدليل كيفية إضافة معاملات اشتراك رقمية إلى "الإجراء الحواري"، حتى يتمكّن المستخدمون من شراء اشتراكاتك.

المصطلحات الرئيسية: سلعة الاشتراك الرقمية هي وحدة تخزين (SKU) تتطلّب رسومًا متكررة من المستخدم، مثل مجلة على الإنترنت. وتختلف هذه السلع عن سلعة رقمية مستهلكة يجب على المستخدم إعادة شرائها يدويًا، أو عن سلعة رقمية غير استهلاكية يتم شراؤها مرة واحدة فقط تلقائيًا.

لمزيد من المعلومات حول الاشتراكات الرقمية، يُرجى الاطّلاع على مستندات Android حول الميزات الخاصة بالاشتراكات.

مسار المعاملة

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

  1. إعداد عميل واجهة برمجة تطبيقات عمليات الشراء الرقمية: يستخدم الإجراء الخاص بك واجهة برمجة تطبيقات عمليات الشراء الرقمية للتواصل مع مستودعك الإعلاني على Google Play ومعاملاتك. قبل أن يفعل الإجراء الخاص بك أي شيء آخر، فإنه ينشئ عميل JWT باستخدام مفتاح خدمة للاتصال بواجهة برمجة تطبيقات عمليات الشراء الرقمية.
  2. جمع المعلومات: يجمع الإجراء الخاص بك معلومات أساسية حول المستخدم ومستودع Google Play الخاص بك للتحضير لمعاملة.
    1. التحقق من متطلبات المعاملات: يستخدم الإجراء الخاص بك مساعد متطلبات المعاملات الرقمية في بداية عملية الشراء للتأكّد من أنّ المستخدم يمكنه إجراء المعاملات.
    2. جمع المستودع الإعلاني المتاح: يتحقّق الإجراء الخاص بك من مستودعك على Google Play ويحدّد السلع المتاحة حاليًا للشراء.
  3. إنشاء الطلب: يعرض الإجراء الخاص بك السلع الرقمية المتاحة للمستخدم حتى يتمكّن من اختيار سلعة لشرائها.
  4. إكمال عملية الشراء: يستخدم الإجراء الخاص بك واجهة برمجة تطبيقات عمليات الشراء الرقمية لبدء عملية شراء من خلال اختيار المستخدم على "متجر Google Play".
  5. معالجة النتيجة: يتلقّى الإجراء الخاص بك رمز حالة للمعاملة ويُبلغ المستخدم بأنّ عملية الشراء تمّت بنجاح (أو يتخذ خطوات إضافية).

القيود وإرشادات المراجعة

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

لا يمكن نشر الإجراءات التي تبيع سلعًا رقمية إلا في البلدان التالية:

  • أستراليا
  • البرازيل
  • كندا
  • إندونيسيا
  • اليابان
  • المكسيك
  • روسيا
  • سنغافورة
  • تايلاند
  • تركيا
  • المملكة المتحدة
  • الولايات المتحدة

المتطلبات الأساسية

قبل دمج المعاملات الرقمية في الإجراء الخاص بك، عليك استيفاء المتطلبات الأساسية التالية:

  • حساب مطوّر برامج وحساب تاجر على Google Play لإدارة السلع الرقمية في Google Play Console.

  • نطاق ويب تم إثبات ملكيته في Google Search Console. لا يلزم إقران هذا النطاق بموقع إلكتروني متاح للجميع، كل ما نحتاج إليه هو الإشارة إلى نطاق الويب الخاص بك.

  • تطبيق Android حاصل على com.android.vending.BILLING إذن في Google Play Console. ستكون سلعك الرقمية عبارة عن "عمليات شراء داخل التطبيق" مرتبطة بهذا التطبيق في Google Play Console.

    عليك أيضًا إنشاء إصدار في Play Console باستخدام هذا التطبيق، ولكن إذا كنت لا تريد إتاحة هذا الإصدار للجميع، يمكنك إنشاء إصدار أولي مغلق.

    إذا لم يكن لديك تطبيق Android حاليًا، اتّبِع تعليمات "ربط تطبيق Android".

  • اشتراك واحد أو أكثر في Google Play Console، وهي السلع الرقمية التي تبيعها من خلال الإجراء الخاص بك. تجدر الإشارة إلى أنّه لا يمكنك إنشاء اشتراكات في Play Console إلا بعد إعداد المتطلبات الأساسية لتطبيق Android.

    إذا لم تكن لديك اشتراكات حاليًا، يُرجى اتّباع تعليمات إنشاء السلع الرقمية الخاصة بك.

ربط تطبيق Android

إذا لم يكن لديك حاليًا تطبيق Android بإذن الفوترة في Google Play Console، يُرجى اتّباع الخطوات التالية:

  1. في استوديو Android أو بيئة التطوير المتكاملة لـ Android التي تختارها، أنشئ مشروعًا جديدًا. حدد الخيارات في مطالبات إعداد المشروع لإنشاء تطبيق أساسي للغاية.
  2. أدخِل اسم حزمة للمشروع، مثل com.mycompany.myapp. لا تترك هذا الاسم كخيار تلقائي، لأنه لا يمكنك تحميل الحِزم التي تتضمّن com.example إلى Play Console.
  3. افتح ملف AndroidManifest.xml الخاص بتطبيقك.
  4. إضافة سطر الرمز التالي داخل العنصر manifest:

    <uses-permission android:name="com.android.vending.BILLING" />

    من المفترَض أن يبدو ملف AndroidManifest.xml على أنّه مجموعة الرموز التالية:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.mycompany.myapp">
        <uses-permission android:name="com.android.vending.BILLING" />
    
        <application
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            android:label="@string/app_name"
            android:roundIcon="@mipmap/ic_launcher_round"
            android:supportsRtl="true"
            android:theme="@style/AppTheme" />
    </manifest>
    
  5. إنشاء تطبيقك على هيئة حزمة APK موقَّعة في "استوديو Android"، اتّبِع الخطوات التالية:

    1. انتقِل إلى الإصدار، ثم إنشاء حزمة Signed Bundle / حِزمة APK.
    2. انقر على التالي.
    3. ضِمن مسار متجر المفاتيح، انقر على إنشاء جديد.
    4. املأ كل حقل، ثم انقر على حسنًا. دوِّن كلمة مرور متجر المفاتيح وكلمة مرور المفتاح، وخزّنهما في مكان آمن، لأنهما ستستخدمهما لاحقًا.
    5. انقر على التالي.
    6. اختَر إصدار.
    7. اختَر V1 (توقيع JAR).
    8. انقر على إنهاء.
    9. بعد بضع ثوانٍ، سينشئ "استوديو Android" ملف app-release.apk. حدِّد موقع هذا الملف لاستخدامه لاحقًا.
  6. في Google Play Console، أنشئ تطبيقًا جديدًا.

  7. انتقِل إلى إصدارات التطبيقات.

  8. ضمن قنوات مغلقة، انتقِل إلى إدارة ثم إصدار أولي.

  9. انقر على الزر إنشاء إصدار.

  10. ضمن السماح لشركة Google بإدارة مفتاح التوقيع وحمايته، أدخِل معلومات مفتاح التوقيع.

  11. حمِّل ملف APK.

  12. انقر على حفظ.

إنشاء السلع الرقمية

إذا لم تكن لديك حاليًا أي سلع رقمية في Play Console، يُرجى اتّباع الخطوات التالية:

  1. في Google Play Console، انتقِل إلى المنتجات داخل التطبيق ثم الاشتراكات. إذا ظهر لك تحذير، اتّبِع التعليمات السابقة لإنشاء تطبيق Android أو انقر على الرابط لإنشاء ملف شخصي للتاجر.
  2. انقر على إنشاء اشتراك.
  3. املأ الحقول الخاصة بمنتجك الرقمي. دوِّن معرّف المنتج، وهو الطريقة التي ستشير بها إلى هذا المنتج من الإجراء الخاص بك.
  4. انقر على حفظ.
  5. كرِّر الخطوات من 2 إلى 4 لكل منتج تريد بيعه.

أمثلة على الاشتراكات في Google Play Console

تحضير مشروع المهام

عند إعداد السلع الرقمية في Google Play Console، عليك تفعيل المعاملات الرقمية وربط مشروع "المهام" بتطبيق Play.

الإعداد

لتفعيل معاملات السلع الرقمية في مشروع Actions (الإجراءات)، يُرجى اتّباع الخطوات التالية:

  1. في وحدة تحكُّم الإجراءات، افتح مشروعك أو أنشئ مشروعًا جديدًا.
  2. يُرجى الانتقال إلى نشر ثم معلومات الدليل.
  3. ضمن معلومات إضافية والمعاملات، ضَع علامة في المربّع نعم ضمن هل تستخدِم إجراءاتك واجهة برمجة تطبيقات الشراء الرقمي لإجراء معاملات السلع الرقمية.
  4. انقر على حفظ.

إنشاء مفتاح واجهة برمجة تطبيقات للسلع الرقمية

لإرسال طلبات إلى واجهة برمجة تطبيقات السلع الرقمية، عليك تنزيل مفتاح حساب خدمة JSON المرتبط بمشروع وحدة تحكّم المهام.

لاسترداد مفتاح حساب الخدمة، اتّبِع الخطوات التالية:

  1. في وحدة تحكم الإجراءات، انقر على رمز النقاط الثلاث في الزاوية العلوية اليسرى، ثم إعدادات المشروع.
  2. ابحث عن رقم تعريف مشروع الإجراء.
  3. يُرجى اتّباع هذا الرابط واستبدال "<project_id>" بمعرّف المشروع: https://console.developers.google.com/apis/credentials?project=project_id
  4. في شريط التنقّل الرئيسي، انتقِل إلى بيانات الاعتماد.
  5. في الصفحة التي تظهر، انقر على إنشاء بيانات اعتماد، ثم مفتاح حساب الخدمة.
  6. انتقِل إلى حساب الخدمة، وانقر على حساب خدمة جديد.
  7. امنح حساب الخدمة اسمًا مثل Digitaltransactions.
  8. انقر على إنشاء.
  9. اضبط الدور على المشروع > المالك.
  10. انقر على متابعة.
  11. انقر على إنشاء مفتاح.
  12. اختَر نوع المفتاح JSON.
  13. انقر على إنشاء مفتاح ونزِّل مفتاح حساب خدمة JSON.

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

الربط بمستودعك على Play

للوصول إلى السلع الرقمية من مشروع Actions، عليك ربط نطاق الويب والتطبيق بمشروعك كـ مواقع مرتبطة.

لربط تطبيق ونطاق الويب في Play Console بمشروع الإجراءات، اتّبِع الخطوات التالية:

  1. في وحدة تحكّم الإجراءات، انتقِل إلى نشر ثم إثبات ملكية العلامة التجارية.
  2. إذا لم تكن قد ربطت أي مواقع، عليك ربط موقع إلكتروني أولاً:

    1. انقر على زر موقع الويب (</>).
    2. أدخِل عنوان URL لنطاق الويب وانقر على ربط.

    ترسل Google رسالة إلكترونية تتضمّن المزيد من التعليمات إلى الفرد الذي تم إثبات ملكيته لنطاق الويب هذا في Google Search Console. بعد أن يتّبع مستلِم هذه الرسالة الإلكترونية هذه الخطوات، من المفترض أن يظهر الموقع الإلكتروني ضمن إثبات ملكية العلامة التجارية.

  3. بعد أن يصبح لديك موقع ويب مرتبط واحد على الأقل، نفِّذ الخطوات التالية لربط تطبيق Android:

    1. في وحدة تحكّم الإجراءات، انتقِل إلى نشر ثم إثبات ملكية العلامة التجارية.
    2. انقر على ربط التطبيق.
    3. في الصفحة التي تظهر، اتّبِع التعليمات لإثبات ملكية نطاق الويب على Play Console. اختَر تطبيق Play الذي يتضمّن السلع الرقمية ثم أدخِل عنوان URL لنطاق الويب كما يظهر بالضبط في صفحة إثبات ملكية العلامة التجارية.

      ترسل Google مرة أخرى رسالة تحقق إلى المالك المعتمد للنطاق. بعد موافقته على إثبات الملكية، من المفترض أن يظهر تطبيقك على Play ضمن التحقق من العلامة التجارية.

    4. تفعيل الوصول إلى عمليات الشراء في Play

صورة تعرض الموقع الإلكتروني والتطبيقات المرتبطة بمشروع &quot;المهام&quot;

بناء تدفق الشراء

بعد تجهيز مشروع "المهام" ومستودع السلع الرقمية، يمكنك إنشاء تدفق شراء السلع الرقمية في الرد التلقائي على الويب لتنفيذ المحادثات.

1- إعداد عميل واجهة برمجة التطبيقات للمشتريات الرقمية

في الرد التلقائي على الويب لتنفيذ المحادثة، أنشئ برنامج JWT باستخدام مفتاح JSON لحساب الخدمة ونطاق https://www.googleapis.com/auth/actions.purchases.digital.

ينشئ رمز Node.js التالي عميل JWT لواجهة برمجة التطبيقات للمشتريات الرقمية:

  const serviceAccount = {'my-file.json'};
  const request = require('request');
  const {google} = require('googleapis');

  const jwtClient = new google.auth.JWT(
    serviceAccount.client_email, null, serviceAccount.private_key,
    ['https://www.googleapis.com/auth/actions.purchases.digital'],
    null
  );

2. جمع المعلومات

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

2. أ. التحقّق من متطلبات المعاملة

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

لإنشاء المشهد الرقمي للشراء، اتّبِع الخطوات التالية:

  1. من علامة التبويب مشاهد، أضِف مشهدًا جديدًا باسم DigitalPurchaseCheck.
  2. ضمن ملء الفتحة، انقر على + لإضافة خانة جديدة.
  3. ضمن اختيار النوع، اختَر actions.type.DigitalPurchaseCheckResult كنوع الخانة.
  4. في حقل اسم الخانة، أدخِل الاسم DigitalPurchaseCheck.
  5. فعِّل مربّع الاختيار تخصيص قيمة الخانة لاحقًا (مفعّلة تلقائيًا).
  6. انقر على حفظ.

تؤدّي عملية التحقّق من الشراء الرقمي إلى التوصّل إلى إحدى النتائج التالية:

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

لمعالجة نتيجة التحقّق من عملية الشراء الرقمية، يُرجى اتّباع الخطوات التالية:

  1. من علامة التبويب مشاهد، اختَر مشهد DigitalPurchaseCheck الذي تم إنشاؤه حديثًا.
  2. ضمن الشرط، انقر على + لإضافة شرط جديد.
  3. في حقل النص، أدخل بناء جملة الشرط التالي للتحقق من شرط النجاح:

    scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
    
  4. مرِّر مؤشر الماوس فوق الشرط الذي أضفته للتو وانقر على السهم المتّجه للأعلى لوضعه قبل if scene.slots.status == "FINAL".

  5. تفعيل إرسال المطالبات وتقديم رسالة مطالبة بسيطة تتيح للمستخدم معرفة أنّه مستعد لإجراء معاملة:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                You are ready to purchase digital goods.
    
  6. ضمن النقل، اختَر مشهدًا آخر، مما يسمح للمستخدم بمواصلة المحادثة ومتابعة إجراء المعاملة.

  7. اختَر الشرط else if scene.slots.status == "FINAL".

  8. فعِّل إرسال الطلبات وقدِّم رسالة مطالبة بسيطة تخبر المستخدم بأنّه غير قادر على إجراء معاملة:

    candidates:
      - first_simple:
          variants:
            - speech: Sorry you cannot perform a digital purchase.
    
  9. ضمن النقل، انقر على إنهاء المحادثة لإنهاء المحادثة.

2. ب. جمع المستودع الإعلاني المتاح

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

يتم تمثيل كل سلعة رقمية كرمز تخزين تعريفي بتنسيق JSON. يوضح رمز Node.js التالي التنسيق المتوقع لكل رمز تخزين تعريفي:

body = {
  skus: [
    skuId: {
      skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
      id: string,
      packageName: string
    }
    formattedPrice: string,
    title: string,
    description: string
  ]
}

يمكنك إرسال طلب POST إلى نقطة نهاية https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet، حيث يشير {packageName} إلى اسم حزمة تطبيقك في Google Play Console (على سبيل المثال، com.myapp.digitalgoods)، وتنسيق النتيجة في مصفوفة من كائنات رموز التخزين التعريفية.

لاسترداد سلع رقمية معيّنة فقط في المصفوفة الناتجة، أدرِج أرقام تعريف المنتجات الرقمية (كما هو موضّح أسفل كل منتج داخل التطبيق في Google Play Console) تريد إتاحتها للشراء في body.ids.

يطلب رمز Node.js التالي قائمة بالسلع المتاحة من Digital purchases API وينسق النتيجة كمصفوفة من رموز التخزين التعريفية:

return jwtClient.authorize((err, tokens) => {
    if (err) {
      throw new Error(`Auth error: ${err}`);
    }

    const packageName = 'com.example.projectname';

    request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
      'auth': {
        'bearer': tokens.access_token,
      },
      'json': true,
      'body': {
        'conversationId': conv.session.id,
        'skuType': 'SKU_TYPE_IN_APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['annual.subscription']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

3. بناء الطلب

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

يقرأ رمز Node.js التالي صفيف مستودع من كائنات SKU وينشئ استجابة قائمة مع عنصر قائمة واحد لكل منها:

const items = [];
const entries = [];
skus.forEach((sku) => {
   const key = `${sku.skuId.skuType},${sku.skuId.id}`
   items.push({
       key: key
   });
   entries.push({
       name: key,
       synonyms: [],
       display: {
           title: sku.title,
           description: `${sku.description} | ${sku.formattedPrice}`,
       }
   });
});

conv.session.typeOverrides = [{
   name: 'type_name',
   mode: 'TYPE_REPLACE',
   synonym: {
       entries: entries
   }
}];

conv.add(new List({
   title: 'List title',
   subtitle: 'List subtitle',
   items: items,
}));

إنشاء عملية شراء من اختيار المستخدمين

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

conv.session.params.purchase = {
  "@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
  "skuId": {
    "skuType": "<SKU_TYPE_IN_APP>",
    "id": "<SKU_ID>",
    "packageName": "<PACKAGE_NAME>"
  },
  "developerPayload": ""
};

بدلاً من ذلك، يمكنك في "أداة إنشاء الإجراءات" استخدام محرِّر JSON لضبط الخانة باستخدام كائن الترتيب أعلاه. تستخدم كلتا الطريقتين التنسيق نفسه للسمة CompletePurchaseValueSpec، ويمكنك العثور عليهما في مرجع حمولة بيانات JSON للردّ التلقائي على الويب.

4. إكمال عملية الشراء

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

إنشاء مشهد كامل لعملية الشراء

  1. من علامة التبويب مشاهد، أضِف مشهدًا جديدًا باسم CompletePurchase.
  2. ضمن ملء الفتحة، انقر على + لإضافة خانة جديدة.
  3. ضمن اختيار نوع، اختَر actions.type.CompletePurchaseValue كنوع الخانة.
  4. في حقل اسم الخانة، أدخِل الاسم CompletePurchase.
  5. فعِّل مربّع الاختيار تخصيص خانة كتابة قيمة الخانة (مفعّل تلقائيًا).
  6. ضمن إعداد الخانة، اختَر Use session parameter من القائمة المنسدلة.
  7. ضمن ضبط الخانة، أدخِل اسم معلمة الجلسة المستخدَمة لتخزين الطلب في حقل النص (أي $session.params.purchase).
  8. انقر على حفظ.

5. التعامل مع النتيجة

يمكن أن تؤدي الخانة من النوع actions.type.CompletePurchaseValue إلى النتائج التالية:

  • PURCHASE_STATUS_OK: تمت عملية الشراء بنجاح. تكتمل المعاملة في هذه المرحلة، لذا اخرج من مسار المعاملات وعُد إلى محادثتك.
  • PURCHASE_STATUS_ALREADY_OWNED: تعذّر إكمال المعاملة لأنّ المستخدم يملك هذا العنصر حاليًا. تجنَّب هذا الخطأ من خلال مراجعة عمليات الشراء السابقة للمستخدم وتخصيص السلع المعروضة حتى لا يتوفّر له خيار إعادة شراء السلع التي سبق أن يملكها.
  • PURCHASE_STATUS_ITEM_UNAVAILABLE: تعذّر إكمال المعاملة لأنّ العنصر المطلوب غير متوفّر. تجنَّب هذا الخطأ عن طريق التحقّق من رموز التخزين التعريفية المتاحة في وقت أقرب إلى وقت الشراء.
  • PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: تعذّر إكمال المعاملة لأنّ المستخدم قرّر شراء منتج آخر. اطلب من المستخدم تقديم طلبك لكي يتمكّن من اتخاذ قرار آخر في الحال.
  • PURCHASE_STATUS_USER_CANCELLED: تعذّر إكمال المعاملة لأنّ المستخدم ألغى مسار الشراء. وبما أنّ المستخدم خرج من العملية مبكرًا قبل أوانها، اسأله ما إذا كان يريد إعادة محاولة إجراء المعاملة أو الخروج منها تمامًا.
  • PURCHASE_STATUS_ERROR: تعذّر إكمال المعاملة لسبب غير معروف. أخبِر المستخدم بأنّه تعذّر إتمام المعاملة واسأله عما إذا كان يريد إعادة المحاولة.
  • PURCHASE_STATUS_UNSPECIFIED: تعذّر إكمال المعاملة لسبب غير معروف، وكانت حالتها غير معروفة. تعامل مع حالة الخطأ هذه من خلال إعلام المستخدم بفشل المعاملة، واسأله عما إذا كان يريد إعادة المحاولة.

يجب التعامل مع كل من هذه النتائج من المشهد CompletePurchase.

  1. من علامة التبويب مشاهد، اختَر مشهد CompletePurchase الذي تم إنشاؤه حديثًا.
  2. ضمن الشرط، انقر على + لإضافة شرط جديد.
  3. في حقل النص، أدخل بناء جملة الشرط التالي للتحقق من شرط النجاح:

    scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
    
  4. مرِّر مؤشر الماوس فوق الشرط الذي أضفته للتو وانقر على السهم المتّجه للأعلى لوضعه قبل if scene.slots.status == "FINAL".

  5. تفعيل إرسال المطالبات وتقديم رسالة مطالبة بسيطة تتيح للمستخدم معرفة أنّه مستعد لإجراء معاملة:

    candidates:
      - first_simple:
          variants:
            - speech: >-
                Your purchase was successful.
    
  6. ضمن النقل، اختَر إنهاء المحادثة لإنهاء المحادثة.

كرِّر الخطوات السابقة لكل نوع من أنواع نتائج الشراء التي تريد دعمها.

تعكس عمليات الشراء التي أجراها المستخدم

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

يعرض الرمز النموذجي التالي عنصر user للطلب الذي يتضمّن packageEntitlements من عمليات الشراء السابقة داخل التطبيق التي تم إجراؤها لحزمة com.digitalgoods.application:

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
      "packageEntitlements": [
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "non-consumable.1",
              "skuType": "SKU_TYPE_IN_APP"
            }
            {
              "sku": "consumable.2",
              "skuType": "SKU_TYPE_IN_APP"
            }
          ]
        },
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "annual.subscription",
              "skuType": "SKU_TYPE_SUBSCRIPTION",
              "inAppDetails": {
                "inAppPurchaseData": {
                  "autoRenewing": true,
                  "purchaseState": 0,
                  "productId": "annual.subscription",
                  "purchaseToken": "12345",
                  "developerPayload": "HSUSER_IW82",
                  "packageName": "com.digitalgoods.application",
                  "orderId": "GPA.233.2.32.3300783",
                  "purchaseTime": 1517385876421
                },
                "inAppDataSignature": "V+Q=="
              }
            }
          ]
        }
      ]
     }
   },
  "homeStructure": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

اختبار مشروعك

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

  1. في وحدة تحكّم الإجراءات، انقر على اختبار في شريط التنقّل.
  2. انقر على الإعدادات.
  3. فعِّل خيار وضع الحماية للتطوير.