اجرای برنامه‌ها در دستگاه سخت‌افزاری

همیشه برنامه Android خود را قبل‌از انتشار برای کاربران، روی یک دستگاه واقعی آزمایش کنید. این صفحه نحوه راه‌اندازی محیط توسعه نرم‌افزار و دستگاه مجهز به Android را برای آزمایش و اشکال‌زدایی ازطریق اتصال «پل اشکال‌زدایی Android»‏ (ADB) شرح می‌دهد.

راه‌اندازی دستگاه برای توسعه

قبل‌از اینکه بتوانید اشکال‌زدایی را در دستگاهتان شروع کنید، تصمیم بگیرید که می‌خواهید بااستفاده از کابل USB یا Wi-Fi به دستگاه متصل شوید. سپس موارد زیر را انجام دهید:

1. در دستگاه، برنامه تنظیمات را باز کنید، گزینه‌های توسعه‌دهندگان را انتخاب کنید، و سپس اشکال‌زدایی USB را فعال کنید (درصورت وجود).

2. سیستمتان را برای شناسایی دستگاهتان راه‌اندازی کنید.

   • ChromeOS: به پیکربندی اضافی نیاز نیست.
   • macOS: پیکربندی دیگری لازم نیست.
   • Windows: درایور USB برای ADB نصب کنید (درصورت وجود). برای راهنمای نصب و پیوندهای درایورهای OEM، به نصب درایورهای OEM USB مراجعه کنید.

   • Ubuntu Linux: موارد زیر را راه‌اندازی کنید:

     • هر کاربری که می‌خواهد از ADB استفاده کند باید در گروه plugdev باشد. اگر پیام خطایی می‌بینید که می‌گوید در گروه plugdev نیستید، بااستفاده از فرمان زیر خودتان را به آن اضافه کنید:

     sudo usermod -aG plugdev $LOGNAME
     

     گروه‌ها فقط هنگام ورود به سیستم به‌روزرسانی می‌شوند، بنابراین برای اعمال این تغییر باید از سیستم خارج شوید. وقتی دوباره به سیستم وارد شدید، می‌توانید از id استفاده کنید تا بررسی کنید که در گروه plugdev هستید یا نه.

     • سیستم باید قوانین udev نصب‌شده‌ای داشته باشد که دستگاه را پوشش دهد. بسته android-sdk-platform-tools-common حاوی مجموعه پیش‌فرضی از قوانین udev برای دستگاه‌های Android است که توسط انجمن نگهداری می‌شود. برای نصب آن، از فرمان زیر استفاده کنید:

     apt-get install android-sdk-platform-tools-common
     

اتصال به دستگاه بااستفاده از USB

وقتی راه‌اندازی کردید و ازطریق USB متصل شدید، روی اجرا در Android Studio کلیک کنید تا برنامه‌تان را در دستگاه بسازید و اجرا کنید.

همچنین می‌توانید از adb برای صدور فرمان‌ها به‌صورت زیر استفاده کنید:

• با اجرای فرمان adb devices از فهرست راهنمای android_sdk/platform-tools/، بررسی کنید دستگاهتان متصل باشد. اگر متصل باشد، دستگاه را در فهرست خواهید دید.
• هر فرمان adb را با پرچم -d برای هدف قرار دادن دستگاهتان صادر کنید.

اتصال به دستگاه بااستفاده از Wi-Fi

Android 11 و نسخه‌های بالاتر از استقرار و اشکال‌زدایی بی‌سیم برنامه‌تان از ایستگاه کاری بااستفاده از «پل اشکال‌زدایی Android»‏ (ADB) پشتیبانی می‌کند. برای مثال، می‌توانید برنامه قابل‌اشکال‌زدایی‌تان را بدون اتصال فیزیکی دستگاهتان بااستفاده از USB و مواجهه با مشکلات رایج اتصال USB (مانند نصب درایور) در چندین دستگاه ازراه‌دور مستقر کنید.

‫Android 17، درکنار adb 37.0.0، نسخه ۲.۰ از adb Wi-Fi را معرفی می‌کند که بسیاری از مشکلات کاربردپذیری نسخه قبلی را حل می‌کند. به‌ویژه، وقتی دستگاه به شبکه مورداعتماد اشکال‌زدایی بی‌سیم متصل می‌شود، دستگاه به‌طور خودکار به ایستگاه کاری متصل خواهد شد.

برای استفاده از اشکال‌زدایی بی‌سیم، باید دستگاهتان را بااستفاده از کد جفت‌سازی با ایستگاه کاری‌تان جفت کنید. برای شروع، مراحل زیر را تکمیل کنید:

1. مطمئن شوید ایستگاه کاری و دستگاهتان به یک شبکه بی‌سیم متصل باشند.
2. مطمئن شوید دستگاهتان Android نسخه ۱۱ یا بالاتر داشته باشد. برای اطلاعات بیشتر، بررسی و به‌روزرسانی نسخه Android را ببینید.
3. مطمئن شوید که جدیدترین نسخه Android Studio را نصب کرده‌اید. آن را از اینجا بارگیری کنید.
4. در ایستگاه کاری‌تان، به جدیدترین نسخه ابزارهای پلاتفرم کیت توسعه نرم‌افزار به‌روزرسانی کنید.

برای جفت کردن با دستگاهتان، این مراحل را دنبال کنید:

1. گزینه‌های توسعه‌دهندگان را در دستگاهتان فعال کنید.

2. در دستگاهتان، روی «اشکال‌زدایی بی‌سیم» ضربه بزنید.

   

3. اشکال‌زدایی بی‌سیم را در شبکه‌تان مجاز کنید. توجه داشته باشید که با کلیک کردن روی چارگوش انتخاب همیشه در این شبکه مجاز باشد، شبکه به شبکه اشکال‌زدایی بی‌سیم مورد اعتماد تبدیل می‌شود. دستگاهتان همیشه اشکال‌زدایی بی‌سیم را در این شبکه مجاز خواهد کرد به‌محض اینکه دستگاه به شبکه متصل شود.

   

4. Android Studio را باز کنید و جفت کردن دستگاه‌ها بااستفاده از Wi-Fi را از منو پیکربندی‌های اجرا انتخاب کنید.

   

   
   

5. کادر گفتگوی جفت کردن دستگاه‌ها ازطریق Wi-Fi، همان‌طور که در شکل ۴ نشان داده شده است، ظاهر می‌شود.

   

   یا می‌توانید دستگاه را از مدیر دستگاه جفت کنید. برای مثال My Pixel.

   

   
   

6. روی Pair در دستگاهی که می‌خواهید جفت شود کلیک کنید. کادر گفتگوی جفت‌سازی دستگاه نشان داده می‌شود.

   1. برای جفت کردن دستگاه با رمزینه پاسخ‌سریع، جفت کردن دستگاه با رمزینه پاسخ‌سریع را انتخاب کنید و رمزینه پاسخ‌سریع را اسکن کنید.

      

   2. برای جفت کردن دستگاهتان با کد جفت‌سازی، جفت کردن دستگاه با کد جفت‌سازی را از کادر گفتگوی جفت کردن دستگاه‌های جدید ازطریق Wi-Fi انتخاب کنید. در دستگاهتان، جفت کردن بااستفاده از کد جفت‌سازی را انتخاب کنید. کدی شش رقمی ظاهر می‌شود. وقتی دستگاهتان در پنجره جفت کردن دستگاه‌ها ازطریق Wi-Fi نشان داده شد، کد شش‌رقمی نشان‌داده‌شده در دستگاهتان را وارد کنید و جفت کردن را انتخاب کنید.

      

7. پس‌از مرتبط‌سازی، می‌توانید برنامه‌تان را در دستگاهتان مستقر کنید.

برای لغو جفت کردن ایستگاه کاری، به اشکال‌زدایی بی‌سیم در دستگاهتان بروید. روی نام ایستگاه کاری‌تان در بخش دستگاه‌های جفت‌شده تک‌ضرب بزنید و فراموش کردن را انتخاب کنید. یا می‌توانید روی لغو مجوزهای اشکال‌زدایی adb در صفحه «تنظیمات» دستگاهتان کلیک کنید تا جفت‌سازی ایستگاه کاری‌تان و همه ایستگاه‌های کاری دیگری که قبلاً جفت شده‌اند لغو شود.

آینه‌سازی دستگاه

می‌توانید دستگاه فیزیکی‌تان را در پنجره دستگاه‌های درحال اجرا در Android Studio قرینه‌سازی کنید. با جاری‌سازی نمایشگر دستگاه مستقیماً در Android Studio، می‌توانید از خود Studio IDE برای اجرای کنش‌های رایج مانند راه‌اندازی برنامه‌ها و تعامل با آن‌ها، چرخاندن صفحه‌نمایش، تا کردن و باز کردن تلفن، و تغییر میزان صدا استفاده کنید.

هرگاه دستگاه‌هایی به رایانه متصل باشند که اشکال‌زدایی USB یا بی‌سیم در آن‌ها فعال باشد، قرینه‌سازی دستگاه همیشه دردسترس است. می‌توانید بااستفاده از پنجره دستگاه‌های درحال اجرا یا مدیر دستگاه (مشاهده > پنجره‌های ابزار > مدیر دستگاه) آینه‌سازی را شروع و متوقف کنید. همچنین می‌توانید زمان فعال شدن آینه‌سازی دستگاه را در تنظیمات آن سفارشی‌سازی کنید (تنظیمات > ابزارها > آینه‌سازی دستگاه).

هدایت کردن صدا

وقتی از قرینه‌سازی دستگاه استفاده می‌کنید، می‌توانید صدا را از دستگاه‌های فیزیکی متصل به بلندگوها یا هدفون رایانه‌تان هدایت کنید. با هدایت صوتی، هدفونتان را به رایانه متصل نگه دارید و بدون نیاز به اتصال مجدد دستی به یک دستگاه و سپس دستگاه دیگر، به صدای رایانه و تلفن متصل گوش دهید. برای فعال کردن تغییر مسیر صدا، به File (فایل) (Android Studio در macOS) > Settings (تنظیمات) > Tools (ابزارها) > Device Mirroring (قرینه‌سازی دستگاه) بروید و Redirect audio from local devices (تغییر مسیر صدا از دستگاه‌های محلی) را انتخاب کنید. توجه داشته باشید که صدا همیشه هدایت می‌شود، صرف‌نظر از تنظیمات، برای دستگاه‌های Firebase Test Lab که Android 12 یا بالاتر دارند.

مشکلات شناخته‌شده

برخی‌از دستگاه‌ها ممکن است نتوانند با نرخ بیتی کدبندی کنند که برای پشتیبانی از قرینه‌سازی دستگاه کافی باشد. در این شرایط، ممکن است خطایی در پنجره دستگاه‌های درحال اجرا و همچنین گزارش‌هایی مشابه موارد زیر ببینید.

2023-06-01 15:32:22,675 [  56094]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - Too many video encoder errors:
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - encoder: c2.android.vp8.encoder
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - mime type: video/x-vnd.on2.vp8
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max resolution: 640x640
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - min resolution: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - alignment: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate: 960
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate for 288x640: 960
2023-06-01 15:32:22,870 [  56289]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max bitrate: 20000000
2023-06-01 15:32:22,871 [  56290]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - terminated with code 1

ابلاغیه حریم خصوصی

براساس تنظیمات قرینه‌سازی دستگاه، Android Studio می‌تواند به‌طور خودکار قرینه‌سازی دستگاه را برای هر دستگاه متصل و جفت‌شده‌ای شروع کند. این امر ممکن است منجر به افشای اطلاعات برای دستگاه‌های متصل‌شده با فرمان adb tcpip شود زیرا اطلاعات و فرمان‌های قرینه‌سازی ازطریق کانال غیررمزگذاری‌شده منتقل می‌شوند. علاوه‌براین، Android Studio از کانال رمزگذاری‌نشده‌ای برای ارتباط با سرور adb استفاده می‌کند، بنابراین اطلاعات آینه‌سازی می‌تواند توسط کاربران دیگر در ماشین میزبان شما رهگیری شود.

عیب‌یابی اتصال دستگاه

اگر دستگاهتان به Android Studio متصل نمی‌شود، مراحل زیر را برای رفع مشکل امتحان کنید:

عیب‌یابی با «دستیار اتصال»

«دستیار اتصال» دستورالعمل‌های گام‌به‌گام برای کمک به شما در راه‌اندازی و استفاده از دستگاه ازطریق اتصال ADB ارائه می‌دهد.

برای شروع دستیار، ابزارها > عیب‌یابی اتصالات دستگاه را انتخاب کنید.

«دستیار اتصال» دستورالعمل‌ها، کنترل‌های درون‌بافتی، و فهرستی از دستگاه‌های متصل‌شده را در مجموعه‌ای از صفحه‌ها در پانل دستیار ارائه می‌دهد. از دکمه‌های بعدی و قبلی در پایین پانل دستیار برای کار کردن با صفحه‌ها درصورت نیاز استفاده کنید:

• متصل کردن دستگاه ازطریق USB: «دستیار اتصال» ابتدا از شما می‌خواهد دستگاهتان را ازطریق USB متصل کنید و دکمه اسکن مجدد دستگاه‌های USB را ارائه می‌دهد که در آنجا می‌توانید اسکن جدیدی برای دستگاه‌های متصل‌شده شروع کنید.
• فعال کردن اشکال‌زدایی USB: سپس «دستیار اتصال» به شما می‌گوید که چگونه اشکال‌زدایی USB را در گزینه‌های توسعه‌دهندگان در دستگاه فعال کنید.
• بازراه‌اندازی سرور ADB: اگر هنوز دستگاهتان را در فهرست دستگاه‌های دردسترس نمی‌بینید، از دکمه بازراه‌اندازی سرور ADB در صفحه آخر «دستیار اتصال» استفاده کنید. بازراه‌اندازی سرور ADB همچنین باعث می‌شود ADB دوباره دستگاه‌ها را اسکن کند. اگر هنوز دستگاهتان را در فهرست دستگاه‌های دردسترس نمی‌بینید، مراحل عیب‌یابی را در بخش زیر امتحان کنید.

برطرف کردن مشکلات اتصال USB

اگر «دستیار اتصال» دستگاهتان را ازطریق USB شناسایی نمی‌کند، مراحل عیب‌یابی زیر را برای حل مشکل امتحان کنید:

بررسی کنید که «استودیو Android» به «شبیه‌ساز Android» متصل می‌شود

برای بررسی اینکه آیا مشکل به‌دلیل مشکل اتصال بین Android Studio و «شبیه‌ساز Android» ایجاد شده است یا نه، این مراحل را دنبال کنید:

1. مدیر دستگاه را باز کنید.
2. اگر ازقبل AVD ندارید، AVD جدیدی ایجاد کنید.
3. بااستفاده از AVD، شبیه‌ساز را اجرا کنید.
4. یکی از کارهای زیر را انجام دهید:
   • اگر Android Studio نمی‌تواند به شبیه‌ساز متصل شود، جدیدترین ابزارهای پلاتفرم SDK را بارگیری کنید و سپس دوباره امتحان کنید.
   • اگر شبیه‌ساز با موفقیت شروع شد، کابل USB را همان‌طور که در بخش زیر توضیح داده شده است بررسی کنید.

بررسی کابل USB

برای بررسی اینکه آیا مشکل به‌دلیل کابل USB معیوب است یا نه، مراحل این بخش را دنبال کنید.

اگر کابل USB دیگری دارید:

1. دستگاه را بااستفاده از کابل ثانویه متصل کنید.
2. بررسی کنید آیا «دستیار اتصال» اکنون می‌تواند دستگاه را شناسایی کند یا نه.
3. اگر دستگاه شناسایی نشد، کابل اصلی را دوباره امتحان کنید.
4. اگر دستگاه همچنان شناسایی نشد، فرض کنید مشکل از دستگاه است و بررسی کنید که آیا دستگاه برای توسعه راه‌اندازی شده است یا نه، همان‌طور که در بخش زیر توضیح داده شده است.

اگر کابل USB دیگری ندارید اما دستگاه Android دیگری دارید:

1. دستگاه ثانویه را به رایانه وصل کنید.

2. اگر «دستیار اتصال» بتواند دستگاه ثانویه را شناسایی کند، فرض کنید که مشکل از دستگاه اصلی است و بررسی کنید که آیا دستگاه برای توسعه راه‌اندازی شده است یا نه.

   اگر دستگاه ثانویه شناسایی نشد، ممکن است مشکل از کابل USB باشد.

بررسی کنید دستگاه برای توسعه راه‌اندازی شده باشد

برای بررسی اینکه آیا مشکل به‌دلیل تنظیمات دستگاه است یا نه، این مراحل را دنبال کنید:

1. مراحل بخش راه‌اندازی دستگاه برای توسعه را دنبال کنید.
2. اگر مشکل برطرف نشد، برای دریافت راهنمایی با پشتیبانی مشتری سازنده اصلی محصول دستگاه تماس بگیرید. به نماینده پشتیبانی مشتری بگویید که دستگاه بااستفاده از ADB به Android Studio متصل نمی‌شود.

برطرف کردن مشکلات اتصال بی‌سیم

اگر در اتصال بی‌سیم به دستگاهتان مشکل دارید، مراحل عیب‌یابی زیر را برای حل مشکل امتحان کنید:

بررسی کنید آیا ایستگاه کاری و دستگاهتان پیش‌نیازها را برآورده می‌کنند یا نه

بررسی کنید که ایستگاه کاری و دستگاه از پیش‌نیازها برخوردار باشند.

بررسی راهنمای عیب‌یابی adb

راهنمای عیب‌یابی adb را دنبال کنید.

کلید امنیتی RSA

وقتی دستگاهی با Android نسخه ۴.۲.۲ (سطح API‏ ۱۷) یا بالاتر را به رایانه‌تان وصل می‌کنید، سیستم کادر گفتگویی نشان می‌دهد که می‌پرسد آیا کلید RSA را که امکان اشکال‌زدایی ازطریق این رایانه را فراهم می‌کند می‌پذیرید یا نه. این سازوکار امنیتی از دستگاه‌های کاربر محافظت می‌کند زیرا اشکال‌زدایی USB و دیگر فرمان‌های adb اجرا نمی‌شوند مگراینکه بتوانید قفل دستگاه را باز کنید و کادر گفتگو را تأیید کنید.