أجهزة تلفزيون مقبض

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

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

البحث عن جهاز تلفزيون

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

الطريقة المقترَحة لتحديد ما إذا كان تطبيقك قيد التشغيل على جهاز تلفزيون هي استخدام طريقة PackageManager.hasSystemFeature للتحقّق مما إذا كان الجهاز قيد التشغيل في وضع التلفزيون. يوضّح مثال الرمز البرمجي التالي كيفية التحقّق مما إذا كان تطبيقك قيد التشغيل على جهاز تلفزيون:

const val TAG = "DeviceTypeRuntimeCheck"

val isTelevision = packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK)
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device")
} else {
    Log.d(TAG, "Running on a non-TV Device")
}
Hardware.kt

public static final String TAG = "DeviceTypeRuntimeCheck";

boolean isTelevision = getPackageManager().hasSystemFeature(PackageManager.FEATURE_LEANBACK);
if (isTelevision) {
    Log.d(TAG, "Running on a TV Device");
} else {
    Log.d(TAG, "Running on a non-TV Device");
}

التعامل مع ميزات الأجهزة غير المتوافقة

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

ميزات أجهزة التلفزيون غير المتوافقة

تختلف أجهزة التلفزيون عن الأجهزة الأخرى، لذا لا تتضمّن ميزات الأجهزة التي تتضمّنها غالبًا الأجهزة الأخرى التي تعمل بنظام التشغيل Android. لهذا السبب، لا يتيح نظام Android الميزات التالية لجهاز التلفزيون:

ملاحظة: تتضمّن بعض وحدات التحكّم في التلفزيون ميكروفونًا، وهو ليس ميزة الأجهزة الميكروفون الموضّحة هنا. يتوافق الميكروفون في وحدة التحكّم بشكل كامل.

للحصول على قائمة كاملة بالميزات والميزات الفرعية والأوصاف الخاصة بها، يُرجى الاطّلاع على مرجع الميزات.

الإعلان عن متطلبات الأجهزة للتلفزيون

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

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

<uses-feature android:name="android.hardware.touchscreen"
        android:required="false"/>
<uses-feature android:name="android.hardware.faketouch"
        android:required="false"/>
<uses-feature android:name="android.hardware.telephony"
        android:required="false"/>
<uses-feature android:name="android.hardware.camera"
        android:required="false"/>
<uses-feature android:name="android.hardware.nfc"
        android:required="false"/>
<uses-feature android:name="android.hardware.location.gps"
        android:required="false"/>
<uses-feature android:name="android.hardware.microphone"
        android:required="false"/>
<uses-feature android:name="android.hardware.sensor"
        android:required="false"/>
<!-- Some TV devices have an ethernet connection only -->
<uses-feature android:name="android.hardware.wifi"
        android:required="false"/>

ملاحظة: تتضمّن بعض الميزات ميزات فرعية، مثل android.hardware.camera.front, كما هو موضّح في مرجع الميزات. احرص على وضع علامة required="false" على أي ميزات فرعية مستخدَمة أيضًا في تطبيقك.

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

تنبيه: يؤدي الإعلان عن ميزة جهاز على أنّها مطلوبة من خلال ضبط قيمتها على true إلى منع تثبيت تطبيقك على أجهزة التلفزيون أو ظهوره في مشغّل الشاشة الرئيسية لنظام Android TV.

التعرّف على الأذونات التي تشير إلى ميزات الأجهزة

تشير بعض إعلانات uses-permission في البيان إلى ميزات الأجهزة. يعني هذا السلوك أنّ طلب بعض الأذونات في بيان تطبيقك يمكن أن يمنع تثبيت تطبيقك واستخدامه على أجهزة التلفزيون. تنشئ الأذونات المطلوبة بشكل شائع التالية متطلبًا ضمنيًا لميزة الجهاز:

للحصول على قائمة كاملة بطلبات الأذونات التي تشير إلى متطلب ميزة الجهاز، يُرجى الاطّلاع على دليل uses-feature. إذا كان تطبيقك يطلب إحدى الميزات المدرَجة سابقًا، أدرِج إعلان uses-feature في بيانك لميزة الجهاز الضمنية التي تشير إلى أنّها غير مطلوبة. android:required="false".

ملاحظة: إذا كان تطبيقك يستهدف Android 5.0 (مستوى واجهة برمجة التطبيقات 21) أو أعلى ويستخدم الإذن ACCESS_COARSE_LOCATION أو ACCESS_FINE_LOCATION، سيظل بإمكان المستخدمين تثبيت تطبيقك على جهاز تلفزيون، حتى إذا لم يكن جهاز التلفزيون يتضمّن بطاقة شبكة أو جهاز استقبال GPS.

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

لمزيد من المعلومات حول فلترة الميزات والإعلان عنها في البيان، يُرجى الاطّلاع على دليل uses-feature.

التحقّق من ميزات الأجهزة

يمكن أن يخبرك إطار عمل Android بما إذا كانت ميزات الأجهزة غير متوفّرة على الجهاز الذي يتم تشغيل تطبيقك عليه. استخدِم طريقة hasSystemFeature(String) للتحقّق من ميزات معيّنة في وقت التشغيل. تأخذ هذه الطريقة وسيطة سلسلة واحدة تحدّد الميزة التي تريد التحقّق منها.

يوضّح مثال الرمز البرمجي التالي كيفية رصد توفّر ميزات الأجهزة في وقت التشغيل:

// Check whether the telephony hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls")
}

// Check whether android.hardware.touchscreen feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.")
}
Hardware.kt

// Check whether the telephony hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) {
    Log.d("HardwareFeatureTest", "Device can make phone calls");
}

// Check whether android.hardware.touchscreen feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_TOUCHSCREEN)) {
    Log.d("HardwareFeatureTest", "Device has a touchscreen.");
}

الشاشة التي تعمل باللمس

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

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

التعريف عن دعم اللمس

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

إذا كان تطبيقك يتيح وضع اللمس، يمكنك الإعلان عن إتاحة اللمس من خلال إضافة android.software.leanback.supports_touch وضبط قيمته على true في ملف AndroidManifest.xml:

<meta-data android:name="android.software.leanback.supports_touch" android:value="true|false"/>

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

الكاميرا

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

<uses-feature android:name="android.hardware.camera" android:required="false" />

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

// Check whether the camera hardware feature is available.
if (packageManager.hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!")
} else {
    Log.d("Camera test", "No camera available. View and edit features only.")
}
Hardware.kt

// Check whether the camera hardware feature is available.
if (getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA)) {
    Log.d("Camera test", "Camera available!");
} else {
    Log.d("Camera test", "No camera available. View and edit features only.");
}

نظام تحديد المواقع العالمي (GPS)

أجهزة التلفزيون هي أجهزة ثابتة داخلية ولا تتضمّن أجهزة استقبال نظام تحديد المواقع العالمي (GPS) . إذا كان تطبيقك يستخدم معلومات الموقع الجغرافي، سيظل بإمكانك السماح للمستخدمين بالبحث عن موقع جغرافي أو استخدام موفّر موقع جغرافي ثابت، مثل رمز بريدي تم ضبطه أثناء إعداد جهاز التلفزيون.

// Request a static location from the location manager.
val locationManager = this.getSystemService(Context.LOCATION_SERVICE) as LocationManager
val location = locationManager.getLastKnownLocation("static")
if (location == null) {
    Log.e(TAG, "Location is null")
    return
}

// Attempt to get postal code from the static location object.
val geocoder = Geocoder(this)
val address: Address? =
        try {
            geocoder.getFromLocation(location.latitude, location.longitude, 1)?.firstOrNull()
                    ?.apply {
                        Log.d(TAG, postalCode)
                    }
        } catch (e: IOException) {
            Log.e(TAG, "Geocoder error", e)
            null
        }
Hardware.kt

// Request a static location from the location manager.
LocationManager locationManager = (LocationManager) this.getSystemService(
        Context.LOCATION_SERVICE);
Location location = locationManager.getLastKnownLocation("static");

// Attempt to get postal code from the static location object.
Geocoder geocoder = new Geocoder(this);
Address address = null;
try {
  address = geocoder.getFromLocation(location.getLatitude(),
          location.getLongitude(), 1).get(0);
  Log.d("Postal code", address.getPostalCode());

} catch (IOException e) {
  Log.e(TAG, "Geocoder error", e);
}

الإيقاف المؤقت للتشغيل أثناء وضع توفير الطاقة

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

لتجنُّب التشغيل أثناء وضع توفير الطاقة، عليك إلغاء onStop وإيقاف أي محتوى قيد التشغيل حاليًا:

override fun onStop() {
    // App-specific method to stop playback.
    stopPlayback()
    super.onStop()
}

@Override
public void onStop() {
  // App-specific method to stop playback.
  stopPlayback();
  super.onStop();
}

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