هدف گذاری دستگاه برای ماژول های شرطی

هدف گذاری دستگاه برای ماژول های شرطی چیست؟

Device Targeting به شما امکان می دهد ماژول های ویژگی مشروط را بر اساس سخت افزار آنها به دستگاه ها تحویل دهید. برای مثال، می‌توانید برخی از ویژگی‌ها را فقط به دستگاه‌های پیشرفته ارائه کنید و آن را به دستگاه‌هایی که قادر به استفاده از این ویژگی نیستند (یعنی صرفه‌جویی در فضا در این دستگاه‌ها) ارائه نکنید. این بر اساس مفهوم ماژول های ویژگی در Play Feature Delivery است. همانطور که در زیر می بینید، شما این قدرت را دارید که معیارهای هدف را تعریف کنید (در حال حاضر بر اساس RAM، مدل های خاص دستگاه یا ویژگی های سیستم موجود)، و ماژول ها را برای گروه های دستگاه خاص هدف قرار دهید.

سفر توسعه دهنده

در سطح بالا، برای ادغام هدف گذاری دستگاه در برنامه فعلی خود، باید مراحل زیر را انجام دهید:

  1. قابلیتی را توسعه دهید که می‌خواهید فقط به مجموعه‌ای از دستگاه‌ها بر اساس سخت‌افزار آن‌ها ارائه دهید.
    • این ویژگی را به عنوان یک ماژول ویژگی پیاده سازی کنید.
    • در بخش شرایط ماژول AndroidManifest.xml مشخص کنید که به کدام گروه دستگاه ها تحویل داده شود.
  2. پیکربندی Device Targeting خود را ایجاد کنید تا Play بداند چگونه ماژول های ویژگی شما را به دستگاه های کاربر تحویل دهد.
    • API برنامه‌نویس Google Play را تنظیم کنید (اگر قبلاً تکمیل نشده باشد)، این همان چیزی است که برای ارسال تنظیمات DT به Play استفاده می‌کنید.
    • مراحل ایجاد پیکربندی DT را طی کنید
  3. AAB خود را در Play آپلود کنید و آزمایش کنید تا مطمئن شوید همه چیز به درستی پیکربندی شده است

این سند نحوه افزودن Device Targeting برای تحویل مشروط را با استفاده از افزونه Gradle Android توضیح می‌دهد.

ماژول ویژگی مشروط را با Device Targeting ایجاد کنید

اضافه کردن یک ماژول ویژگی به برنامه

Play Feature Delivery به شما امکان می دهد ویژگی های خاصی از برنامه خود را به صورت مشروط یا دانلود شده در صورت تقاضا ارائه دهید، می توانید یک نمای کلی در مورد آن را در اینجا بخوانید. با Device Targeting می توانید یک ویژگی را به صورت مشروط به دستگاه های اختصاص داده شده به گروه های ارائه شده تحویل دهید.

برای استفاده از DT برای تحویل مشروط باید از bundletool نسخه 1.7.0 و بالاتر استفاده کنید. برای این کار باید به صراحت نسخه bundletool را برای پلاگین Android Gradle مشخص کنید. این را می توان در بخش ساخت اسکریپت فایل root build.gradle به دست آورد:

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

برای ایجاد یک ماژول ویژگی از این دستورالعمل ها برای ماژولار کردن برنامه اندروید استفاده کنید.

هنگامی که توسعه ویژگی شما کامل شد، می توانید شرایط تحویل را بر اساس هدف گذاری دستگاه در AndroidManifest.xml ویژگی خود مشخص کنید. شما باید یک شرط گروه دستگاه را در داخل یک عنصر dist:conditions of dist:module ارائه دهید. اطلاعات عمومی در مورد شرایط در اینجا موجود است. برای گروه‌های دستگاه، شرایط جدیدی در دسترس است که در آن می‌توانید همه گروه‌ها را مشخص کنید که این ویژگی باید به آنها تحویل داده شود:

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

به عنوان مثال، فرض کنید که شما یک گروه دستگاهی به نام _my_group 1 تعریف کرده اید (در قسمت ایجاد پیکربندی هدفمندی دستگاه در زیر نحوه تعریف آن را خواهید آموخت). اگر ماژول ویژگی فقط به دستگاه‌های متعلق به دستگاه‌های _my_group 1 تحویل داده شود، AndroidManifest.xml آن باید به شکل زیر باشد:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

برای ویژگی که هم _my_group 1 و هم _my_group 2 را هدف قرار می دهد، AndroidManifest.xml آن به صورت زیر است:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
            <dist:device-group dist:name="my_group_2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

پس از اتمام، می‌توانید بسته نرم‌افزاری Android (AAB) خود را بسازید.

تست محلی

قبل از حرکت، توصیه می‌شود بسته برنامه خود را به صورت محلی آزمایش کنید تا مطمئن شوید همه چیز به درستی تنظیم شده است. با استفاده از bundletool برنامه خود را به صورت محلی می‌سازید و آزمایش می‌کنید، و به صراحت گروه دستگاه صحیح را مشخص می‌کنید. ابتدا از build-apks برای تولید مجموعه‌ای از فایل‌های .apks استفاده می‌کنید و سپس برنامه خود را با استفاده از install-apks در دستگاه متصل اجرا می‌کنید. همچنین می‌توانید مشخص کنید که کدام گروه(های) را می‌خواهید از طریق پرچم device-groups نصب شود. می توانید اطلاعات بیشتر در مورد این روش آزمایش محلی را در اینجا بیابید. لطفاً توجه داشته باشید که این صفحه هنوز برای DT به‌روزرسانی نشده است و بنابراین پرچم گروه‌های دستگاه را ندارد.

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2

روش دیگر : همچنین می‌توانید extract-apks برای استخراج مجموعه‌ای از APK برای یک دستگاه خاص استفاده کنید (با استفاده از get-device-spec همراه با مشخص کردن گروه‌های دستگاه برای این دستگاه). 

bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool extract-apks --apks=/path/to/existing_APK_set.apks --output-dir=/path/to/device_specific_APK_set.apks --device-spec=/path/to/device-spec.json

ایجاد پیکربندی هدف‌گیری دستگاه از طریق Google Play Developer API

شروع به کار با Google Play Developer API (اگر قبلاً تکمیل نشده باشد)

برای پیکربندی Device Targeting (گروه های دستگاه خود را تعریف کنید) باید از Android Publisher API برای آپلود پیکربندی خود در Google Play استفاده کنید. می‌توانید در پیوند بالا درباره API بیشتر بخوانید - برای شروع باید چند مرحله را دنبال کنید :

  1. ایجاد کنید (در صورت نیاز) و پروژه API خود را به کنسول Google Play خود پیوند دهید
  2. یک API Access Client راه اندازی کنید

می‌توانید مرجع API را در اینجا پیدا کنید - بعداً، اگر بخواهید ساخت خود را از طریق API آپلود کنید، از روش‌های Edits استفاده خواهید کرد. علاوه بر این، توصیه می شود قبل از استفاده از API ، این صفحه را مرور کنید .

با استفاده از Device Targeting Configuration API

می توانید از فراخوانی API زیر برای ایجاد پیکربندی هدفمندی دستگاه خود استفاده کنید:

پیکربندی هدف گذاری دستگاه را ایجاد کنید

درخواست HTTP POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
پارامترهای مسیر N/A
درخواست بدن پیکربندی هدف گذاری دستگاه
بدنه پاسخگویی پیکربندی هدف گذاری دستگاه
هدف پیکربندی دستگاه
{
  device_groups: [
    {
      name: string,
      device_selectors: [
        {
          device_ram : {
            min_bytes: integer
            max_bytes: integer
          },
          included_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          excluded_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          required_system_features: [
            {
              name: string
            }
          ],
          forbidden_system_features: [
            {
              name: string
            }
          ]
        }
      ]
    }
  ]
}

زمینه ها:

  • device_tier_config_id (عدد صحیح): شناسه مربوط به پیکربندی هدفمند این دستگاه

  • دستگاه_گروه ها (شیء): تعاریف گروهی

    • نام (رشته): نام گروه دستگاه (شناسه رشته ای که شما تعریف می کنید)
    • device_selectors (object): الزامات دستگاه برای تعلق یک دستگاه به این گروه.
    • device_ram (object): مورد نیاز رم دستگاه
      • min_bytes (عدد صحیح): حداقل RAM مورد نیاز (بر حسب بایت)
      • max_bytes (عدد صحیح): حداکثر RAM مورد نیاز (بر حسب بایت)
    • include_device_ids (object): مدل‌های دستگاهی که باید در این انتخابگر گنجانده شوند (حداکثر 10000 دستگاه_ids در هر گروه). یک دستگاه باید در این لیست باشد تا با انتخابگر مطابقت داشته باشد. این یک شرط ضروری است اما کافی نیست برای مطابقت با انتخابگر کامل (به یادداشت زیر در مورد ترکیب الزامات در یک انتخابگر مراجعه کنید).
      • build_brand (رشته): سازنده دستگاه
      • build_device (رشته): کد مدل دستگاه
    • excluded_device_ids (object): مدل‌های دستگاهی که در این انتخابگر حذف می‌شوند (حداکثر 10000 دستگاه_ids در هر گروه). دستگاهی از این لیست با انتخابگر مطابقت نخواهد داشت حتی اگر با سایر الزامات انتخابگر مطابقت داشته باشد.
      • build_brand (رشته): سازنده دستگاه
      • build_device (رشته): کد مدل دستگاه

    • require_system_features (object): ویژگی هایی که یک دستگاه باید در این انتخابگر گنجانده شود (حداکثر 100 ویژگی در هر گروه). یک دستگاه باید تمام ویژگی های سیستم را در این لیست داشته باشد تا با انتخابگر مطابقت داشته باشد. این یک شرط ضروری است اما کافی نیست برای مطابقت با انتخابگر کامل (به یادداشت زیر در مورد ترکیب الزامات در یک انتخابگر مراجعه کنید).

      مرجع ویژگی های سیستم

      • نام (رشته): یک ویژگی سیستم

    • forbidden_system_features (object): ویژگی هایی که دستگاه نباید توسط این انتخابگر گنجانده شود (حداکثر 100 ویژگی در هر گروه) . اگر دستگاهی دارای هر یک از ویژگی های سیستم در این لیست باشد، با انتخابگر مطابقت ندارد، حتی اگر با سایر الزامات موجود در انتخابگر مطابقت داشته باشد.

      مرجع ویژگی های سیستم

      • نام (رشته): یک ویژگی سیستم

می‌توانید قالب‌بندی صحیح سازنده دستگاه و کد مدل را با استفاده از کاتالوگ دستگاه در کنسول Google Play، با یکی از موارد زیر پیدا کنید:

  • بازرسی دستگاه‌های جداگانه با استفاده از کاتالوگ دستگاه، و یافتن کد سازنده و مدل در مکان‌هایی که در مثال زیر نشان داده شده است (برای یک Google Pixel 4a، سازنده «Google» و کد مدل «sunfish» است)».

    صفحه پیکسل 4a در کاتالوگ دستگاه

    صفحه پیکسل 4a در کاتالوگ دستگاه

  • دانلود CSV دستگاه‌های پشتیبانی‌شده و استفاده از کد سازنده و مدل کد به ترتیب برای فیلدهای build_brand و build_device .

به عنوان مثال، گروه زیر با تمام دستگاه‌های دارای رم بیش از 4 گیگابایت، به جز Pixel 5 (google redfin) و از جمله Pixel 3 (Google Blueline که کمتر از 4 گیگابایت رم دارد) مطابقت دارد.

device_groups: [
  {
    name: "my_group_1",
    device_selectors: [
      {
        device_ram: {
          min_bytes: 4294967296
        },
        excluded_device_ids: [
          {
            build_brand: "google",
            build_device: "redfin"
          }
        ]
      },
      {
        included_device_ids: [
          {
            build_brand: "google",
            build_device: "blueline"
          }
        ]
      }
    ]
  }
]

می توانید آن را به صورت زیر بخوانید:

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

می‌توانید دستورالعمل‌های زیر را برای تأیید اعتبار پیکربندی هدف‌گیری دستگاه خود قبل از آپلود آن در Google Play دنبال کنید.

پیکربندی هدف گذاری دستگاه را با شناسه دریافت کنید

با استفاده از تماس زیر می‌توانید پیکربندی هدف‌گیری دستگاه خاص را با شناسه بازیابی کنید:

درخواست HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
پارامترهای مسیر N/A
درخواست بدن N/A
بدنه پاسخگویی پیکربندی هدف گذاری دستگاه

دریافت لیست تنظیمات هدف گذاری دستگاه

می توانید 10 پیکربندی آخرین هدف دستگاه را با توجه به تماس زیر دریافت کنید (یا با استفاده از پارامتر پرس و جو page_token به طور بهینه یک مجموعه ده تایی را مشخص کنید):

درخواست HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
پارامترهای مسیر N/A
پارامترهای پرس و جو page_token (اختیاری) - برای تعیین یک گروه خاص از 10 DTC استفاده می شود. اگر بیش از 10 DTC ایجاد کرده باشید و دوست دارید DTC هایی را ببینید که قبل از 10 مورد اخیر ایجاد شده اند، مفید است.
درخواست بدن N/A
بدنه پاسخگویی فهرست پیکربندی های هدف گذاری دستگاه

page_token

تأیید پیکربندی هدف‌گیری دستگاه

bundletool شامل دو فرمان است که به شما کمک می‌کند قبل از آپلود کردن آن در Play تأیید کنید که پیکربندی هدف‌گیری دستگاه شما همانطور که در نظر گرفته شده است کار می‌کند.

با bundletool print-device-targeting-config ، می توانید تأیید کنید که فایل JSON شما از نظر نحوی صحیح است و گروه های دستگاه خود را در قالبی خواناتر تجسم کنید.

bundletool print-device-targeting-config --config=mydtc.json

با bundletool evaluate-device-targeting-config ، می توانید ارزیابی کنید که چه گروه هایی با یک دستگاه خاص مطابقت دارند. یا دستگاه مورد نظر خود را به ایستگاه کاری خود وصل کنید و از پرچم --connected-device استفاده کنید. یا یک فایل JSON با ویژگی های دستگاه را به صورت دستی کامپایل می کنید و آن را از طریق پرچم --device-properties ارائه می کنید.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

فایل ویژگی های دستگاه باید یک فایل JSON باشد که از ساختار پروتوباف DeviceProperties پیروی می کند. به عنوان مثال: 

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

در حال آپلود Android App Bundle در Google Play

از طریق API

می‌توانید از Google Play Developer API برای آپلود App Bundle Android خود در Google Play استفاده کنید و پیکربندی خاص Device Targeting را به ساخت خود پیوند دهید.

در اینجا یک مرور کلی از روش‌های ویرایش وجود دارد، همراه با مثال‌های عمیق‌تر در مورد انتشار به تراک‌های مختلف در کنسول Google Play (برای آخرین پیوند، می‌خواهید به جای API پسند APK از API‌های پسند AAB استفاده کنید. در صفحه ذکر شده است). برای تعیین پیکربندی هدفمندی دستگاه برای ساخت خود، هنگام فراخوانی روش edits.bundle.upload ، شناسه پیکربندی را به پارامتر query deviceTierConfigId اضافه می‌کنید، مانند این: 

https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}"

از طریق کنسول Google Play

برای آپلود Android App Bundle خود می توانید دستورالعمل های اینجا را دنبال کنید. آخرین پیکربندی DTC در App Bundle شما اعمال خواهد شد.

کمکی

شروع سریع با استفاده از Curl

در زیر یک مثال (با استفاده از ابزار خط فرمان curl) از ایجاد یک پیکربندی هدف‌گیری دستگاه جدید ، و استفاده از api Edits برای ایجاد ویرایش جدید، آپلود AAB جدید (ارتباط آن با پیکربندی هدف‌گیری دستگاه خاص)، تنظیم مسیر/ پیکربندی را آزاد کنید و ویرایش را انجام دهید (در نتیجه تغییر را عمومی کنید) . مطمئن شوید که مکان آن را داشته باشید:

ابتدا یک پیکربندی هدف‌گیری دستگاه ایجاد کنید و از deviceTierConfigId که پس از تماس موفقیت‌آمیز دریافت خواهید کرد یادداشت کنید.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs

یک ویرایش را شروع کنید - یک شناسه و زمان انقضا برای ویرایش دریافت خواهید کرد. شناسه را برای تماس های زیر ذخیره کنید.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits

AAB را آپلود کنید و پیکربندی هدف‌گیری دستگاه (deviceTierConfigId) را به‌عنوان پارامتر جستار مشخص کنید - در صورت موفقیت آمیز بودن تماس، کد نسخه، sha1 و sha256 ساخت را مشاهده خواهید کرد. کد نسخه را برای تماس بعدی ذخیره کنید.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" --data-binary @$HOME/{aabFile} -H "Content-Type: application/octet-stream" -XPOST https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editID}/bundles?deviceTierConfigId="{deviceTierConfigId}

AAB را به آهنگ مورد نظر اختصاص دهید (برای آزمایش، توصیه می‌شود از مسیر تست داخلی استفاده کنید، اما می‌توانید در مورد آهنگ‌های مختلف بیشتر بخوانید) ، در اینجا ما یک عرضه ساده بدون یادداشت‌های انتشار انجام می‌دهیم، اما می‌توانید این صفحه را بخوانید تا درباره نحوه اجرای مرحله‌بندی عرضه‌ها، نسخه‌های پیش‌نویس و یادداشت‌های انتشار بیشتر بیاموزید. اگر اولین باری است که از Publisher API استفاده می‌کنید، توصیه می‌کنیم این نسخه را به‌عنوان نسخه پیش‌نویس ایجاد کنید و نسخه را در کنسول Google Play خود تکمیل کنید تا مطمئن شوید همه چیز به درستی پیکربندی شده است .

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}', versionCodes: ['{versionCode}'] }]}" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}

تغییرات را انجام دهید (با احتیاط ادامه دهید، زیرا این کار باعث می‌شود که همه تغییرات در Play به آهنگ مورد نظر منتقل شوند )

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit