ملفات APK والمسارات

تتيح لك واجهة برمجة التطبيقات Google Play Developer API تحميل حِزم APK جديدة لتطبيقاتك وإصدارها في قنوات إصدار مختلفة. يتيح لك ذلك نشر إصدارات ألفا وبيتا من تطبيقك، والتي يتم توفيرها للمستخدمين الذين تمت الموافقة عليهم. يتيح لك ذلك أيضًا نشر إصدار طرح على مراحل، والذي يتم إتاحته تلقائيًا لعدد صغير من مستخدمي التطبيق. بعد طرح إصدار الطرح على مراحل، يمكنك زيادة عدد المستخدمين الذين يحصلون على هذا الإصدار من التطبيق تدريجيًا إلى أن يتم في النهاية طرح هذا الإصدار كإصدار "علني".

إضافة حِزم APK وتعديلها

1. حمِّل حزمة APK واحدة أو أكثر من خلال استدعاء طريقة Edits.apks: upload.

   تحمّل هذه الطريقة حِزمة APK إلى "حزمة" تخزين، حيث يمكن تعيينها إلى "قناة إصدار" لنشرها للمستخدمين. (في حال حذف التعديل أو تجاهله، سيتم أيضًا فقدان أي حِزم APK تم تحميلها إلى هذا التعديل).

2. أصدِر حِزم APK في "قنوات الإصدار" من خلال استدعاء Edits.tracks: update. يمكنك طرح حِزم APK في قنوات الإصدار التالية:

   • مسارات الاختبار، مثل "alpha" و"beta"

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

   • مسار الاختبار الداخلي: "qa"

     يتم نشر الإصدارات الداخلية من تطبيقك في مسار الاختبار الداخلي كما هو محدّد في Google Play Console.

   • قناة الإصدار العلني: "production"

     يتم طرح الإصدارات في "قناة الإصدار العلني" لجميع المستخدمين. يمكنك الاستفادة من ميزة "الإصدارات على مراحل" في قناة الإصدار العلني لنشر إصدارك بأمان أولاً إلى نسبة صغيرة من مستخدمي الإصدار العلني ثم زيادة هذه النسبة تدريجيًا مع زيادة ثقتك في الإصدار.

   يجب ألا يضع مستخدمو الوضع البسيط أكثر من حزمة APK واحدة في أي قناة إصدار. يمكن لمستخدمي الوضع المتقدّم الذين يستخدمون ميزة توفير حِزم APK متعددة تحميل صفر أو حِزمة APK واحدة أو أكثر إلى كل مسار.

اسم قناة الإصدار المحدود المخصّصة لشكل الجهاز

يتم إضافة بادئة إلى اسم مسار عامل الشكل باستخدام معرّف محدّد.

شكل الجهاز	بادئة
نظام التشغيل Android Automotive	سيارات
Wear OS	رداء
Android TV	تلفزيون
Android XR	android_xr
‫Google Play Games On PC	google_play_games_pc

كيف يتم احتساب اسم مسار عامل الشكل المحدّد؟

تتضمّن أنواع المسارات الشائعة، مثل مسار الإصدار العلني ومسار الاختبار المفتوح ومسار الاختبار الداخلي، اسم مسار معروفًا.

نوع التتبّع	اسم المقطع الصوتي التلقائي
الإنتاج	إصدار
الاختبار المفتوح	إصدار تجريبي
الاختبار الداخلي	قطر

يمكن احتساب اسم قناة الإصدار لشكل جهاز معيّن على النحو التالي: "[prefix]:defaultTrackName". على سبيل المثال، سيتضمّن عامل الشكل Wear OS قنوات إصدار بالأسماء التالية: "wear:production" و"wear:beta" و"wear:qa".

يتم إنشاء مسارات الاختبار المغلق يدويًا، وتتضمّن أسماء مخصّصة. وبالتالي، فإنّ مسار الاختبار المغلق لجهاز ذي شكل معيّن يحمل الاسم $name سيكون اسم مساره "[prefix]:$name".

مثال على سير عمل حِزمة APK

يوضّح هذا القسم طريقة نموذجية لاستخدام Tracks API. في هذه الحالة، نفترض أنّك تريد تحميل إصدارات جديدة من حزمة APK لكل قناة إصدار، وتحديد عدد من المستخدمين لتلقّي إصدار الطرح على مراحل. (في الواقع، من غير المرجّح أن يتّخذ المطوّر كل هذه الإجراءات في العملية نفسها، بل قد يحدّث الإصدار التجريبي في يوم ما، وينشئ إصدارًا على مراحل في "الإنتاج" في يوم آخر، وهكذا).

1. فتح تعديل جديد، كما هو موضّح في سير عمل التعديلات
2. استدعِ طريقة Edits.apks: upload لكل حزمة APK تريد تحميلها. مرِّر حزمة APK في نص طلب الطريقة. (يؤدي ذلك إلى وضع حزمة APK في مساحة تخزين، ولكن لا يتم طرحها في قناة إصدار أو نشرها). تعرض الطريقة رمز إصدار لكل حزمة APK تحمّلها، وستستخدم رمز الإصدار هذا للإشارة إلى حزمة APK عند طرحها في قناة إصدار.

3. استدعِ طريقة Edits.tracks: update لكل قناة إصدار تريد طرح حِزم APK فيها. في نص الطلب، مرِّر مورد Edits.tracks يحتوي على الإصدار الذي تريد طرحه. على سبيل المثال، لإصدار حزمة APK برمز الإصدار 88، اتّبِع الخطوات التالية:

   {
   "releases": [{
     "versionCodes": ["88"],
     "status": "completed"
   }]
   }

   في هذه المرحلة، لا تزال حِزم APK غير متاحة للمستخدمين. وكما هو الحال مع التعديلات الأخرى، لن يتم نشر التغييرات إلا بعد إرسالها.

4. استدعِ طريقة Edits: commit لتنفيذ التغييرات. بعد إجراء ذلك، سيحصل المستخدمون في كل قناة على الإصدار المعدَّل من حِزمة APK. (كما هو الحال مع جميع التعديلات، قد يستغرق تنفيذ التغييرات عدة ساعات).

عمليات الطرح على مراحل

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

يوضّح هذا القسم الخطوات التي يجب اتّباعها لتنفيذ طرح على مراحل لحزمة APK، ثم ترقيتها إلى إصدار علني:

1. أنشئ تعديلاً كما هو موضّح في سير عمل التعديلات.

2. حمِّل حزمة APK جديدة إلى التعديل باستخدام الطريقة Edits.apks: upload.

3. ابدأ طرح إصدار "inProgress" على مراحل في قناة الإصدار العلني باستخدام الطريقة Edits.tracks: update. اختَر نسبة المستخدمين الذين سيحصلون على حِزمة APK الجديدة. في هذه المرحلة، لن يكون ملف APK متاحًا لأي مستخدمين نهائيين.

   {
   "releases": [{
     "versionCodes": ["99"],
     "userFraction": 0.05,
     "status": "inProgress"
   }]
   }

4. نفِّذ التغييرات في التعديل النشط من خلال استدعاء Edits: commit. خلال الساعات القليلة القادمة، سيتم طرح حزمة APK الجديدة للمستخدمين. سيتلقّى جزء من المستخدمين الذين تحدّدهم ملف APK الجديد.

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

زيادة نسبة المستخدمين في عملية طرح على مراحل

بافتراض أنّ لديك طرحًا على مراحل مستمرًا بنسبة %5، كما هو موضّح في القسم السابق، يوضّح هذا القسم كيفية زيادة النسبة المئوية في حال كان الإصدار يسير بشكل جيد:

1. أنشئ تعديلاً كما هو موضّح في سير عمل التعديلات.

2. غيِّر الطرح على مراحل لإصدار "inProgress" في قناة الإصدار العلني باستخدام طريقة Edits.tracks: update. زيادة نسبة المستخدمين الذين سيحصلون على حِزمة APK الجديدة:

   {
   "releases": [{
     "versionCodes": ["99"],
     "userFraction": 0.1,
     "status": "inProgress"
   }]
   }

3. نفِّذ التغييرات في التعديل النشط من خلال استدعاء Edits: commit. خلال الساعات القليلة القادمة، سيتم طرح حزمة APK الجديدة للمستخدمين. سيتلقّى جزء من المستخدمين الذين تحدّدهم ملف APK الجديد.

إيقاف عملية الطرح على مراحل

بافتراض أنّ لديك طرحًا على مراحل مستمرًا بنسبة %5، كما هو موضّح في القسم السابق، يوضّح هذا القسم كيفية إيقاف الطرح على مراحل في حال اكتشاف مشكلة:

1. أنشئ تعديلاً كما هو موضّح في سير عمل التعديلات.

2. غيِّر الطرح على مراحل لإصدار "inProgress" في قناة الإصدار العلني باستخدام طريقة Edits.tracks: update. اضبط الحالة على "halted".

   {
   "releases": [{
     "versionCodes": ["99"],
     "status": "halted"
   }]
   }

3. نفِّذ التغييرات في التعديل النشط من خلال استدعاء Edits: commit. لن يكون إصدارك متاحًا للمستخدمين الجدد.

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

إكمال عملية الطرح على مراحل

بعد أن تصبح راضيًا عن عملية الطرح على مراحل وتريد طرح الإصدار على جميع المستخدمين، يمكنك ضبط حالة الإصدار على "completed":

1. أنشئ تعديلاً كما هو موضّح في سير عمل التعديلات.

2. غيِّر الطرح على مراحل لإصدار "inProgress" في قناة الإصدار العلني باستخدام طريقة Edits.tracks: update. اضبط الحالة على "completed".

   {
   "releases": [{
     "versionCodes": ["99"],
     "status": "completed"
   }]
   }

3. نفِّذ التغييرات في التعديل النشط من خلال استدعاء Edits: commit. خلال الساعات القليلة القادمة، سيتم طرح حِزمة APK الجديدة للمستخدمين. سيتلقّى جزء من المستخدمين الذين تحدّدهم ملف APK الجديد.

إيقاف عملية طرح مكتملة

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

1. أنشئ تعديلاً كما هو موضّح في سير عمل التعديلات.

2. غيِّر إصدار "completed" في قناة الإصدار العلني باستخدام الطريقة Edits.tracks: update. اضبط الحالة على "halted".

   {
   "releases": [{
     "versionCodes": ["99"],
     "status": "halted"
   }]
   }

3. نفِّذ التغييرات في التعديل النشط من خلال استدعاء Edits: commit. لن يكون إصدارك متاحًا للمستخدمين الجدد أو للمستخدمين الحاليين للترقية إليه.

سيكون الإصدار الذي سيبدأ عرضه بدلاً من الإصدار "completed" هو الإصدار "completed" السابق في المسار الذي تم نشره ولم يتم إيقافه. يُرجى العِلم أنّ هذا يعني أنّه لا يمكنك إيقاف "completed"إصدار في قناة إصدار إلا إذا تم نشر إصدار واحد أو أكثر من "completed" في القناة.

إذا اتصلت برقم GetTrack أو ListTracks أثناء إيقاف إصدار "completed" مؤقتًا، سيظهر "إصدار احتياطي" على أنّه الإصدار المكتمل في قناة تم إيقاف إصدار "completed" السابق فيها مؤقتًا.

على سبيل المثال، إذا كان لديك في البداية مسار alpha يبدو على النحو التالي:

{
  "track": "alpha",
  "releases": [
    {
      "name": "2 (2.0)",
      "versionCodes": [
        "2"
      ],
      "status": "completed"
    }
  ]
}

وأوقفت إصدار "completed" باتّباع الخطوات الواردة في هذا القسم، سيؤدي طلب GetTrack للمسار alpha إلى عرض نتيجة مشابهة لما يلي:

{
  "track": "alpha",
  "releases": [
    {
      "name": "2 (2.0)",
      "versionCodes": [
        "2"
      ],
      "status": "halted"
    },
    {
      "name": "1 (1.0)",
      "versionCodes": [
        "1"
      ],
      "status": "completed"
    }
  ]
}

إذا قررت استئناف إصدار "completed" في وقت لاحق، يمكنك إجراء ذلك من خلال إعادة ضبط حالته على "inProgress" أو "completed". يُرجى العِلم أنّه يمكنك إنشاء إصدار جديد "inProgress" في أعلى الإصدار "completed"، ولكن لن تتمكّن بعد ذلك من استئناف طرح الإصدار "completed" إلا بنسبة %100 (أي إلى الحالة "completed").

ملاحظة: لا يمكنك إيقاف "إصدار احتياطي". لا يمكنك إيقاف إصدار تم طرحه بالكامل إذا كان الإصدار الذي سيصبح إصدارًا احتياطيًا يتضمّن مشاكل متعلّقة بالسياسة تمنع طرحه.

الإصدارات التمهيدية

تتيح لك مسودات الإصدارات تحميل حِزم APK وإنشاء إصدار تلقائيًا من خلال واجهة برمجة التطبيقات، ويمكن نشر هذا الإصدار لاحقًا من خلال Google Play Console. لإنشاء إصدار تمهيدي في قناة إصدار، اتّبِع الخطوات التالية:

1. فتح تعديل جديد، كما هو موضّح في سير عمل التعديلات
2. استدعِ طريقة Edits.apks: upload لكل حزمة APK تريد تحميلها. مرِّر حزمة APK في نص طلب الطريقة. تعرض الطريقة رمز إصدار لكل حزمة APK تحمّلها، وستستخدم رمز الإصدار هذا للإشارة إلى حزمة APK عند تعيينها لإصدار.

3. استدعِ طريقة Edits.tracks: update لكل مسار تريد طرحه. في نص الطلب، مرِّر مورد Edits.tracks الذي يحتوي على إصدار المسودة الذي تريد إنشاءه. على سبيل المثال:

   {
   "releases": [{
     "name": "My draft release",
     "versionCodes": ["88"],
     "status": "draft"
   }]
   }

4. استدعِ طريقة Edits: commit لتنفيذ التغييرات. يمكن الآن فحص الإصدار التجريبي وطرحه من خلال Google Play Console أو واجهة برمجة التطبيقات.

تحديد ملاحظات الإصدار

عند إصدار نسخة جديدة من تطبيقك، يمكنك إبراز الميزات الجديدة للمستخدمين من خلال تحديد ملاحظات الإصدار.

لإجراء ذلك، استخدِم الحقل "releaseNotes" عند تقديم مورد Edits.tracks إلى طريقة Edits.tracks: update.

{
  "releases": [{
      "name": "Release with notes",
      "versionCodes": ["88"],
      "status": "completed",
      "releaseNotes": [
        {"language": "en-US", "text": "Describe what's new in this release."}
      ]
  }]
}