إنشاء تطبيق هاتف افتراضي

يتيح تطبيق الهاتف التلقائي لإطار عمل Android Telecom إبلاغ تطبيقك بحالة المكالمة باستخدام مدير الأدوار وخدمة المكالمات لإنشاء بديل لتطبيق الهاتف التلقائي على جهاز Android، وتنفيذ واجهة برمجة التطبيقات InCallService API. يجب أن يستوفي التنفيذ المتطلبات التالية:

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

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

مثال على تطبيق اتصال
مثال على تطبيق اتصال يستخدم واجهة المستخدم الخاصة به

يتضمّن إطار عمل Android حزمة android.telecom التي تحتوي على فئات تساعدك في إنشاء تطبيق اتصال وفقًا لإطار عمل الاتصالات. يوفّر إنشاء تطبيقك وفقًا لإطار عمل الاتصالات المزايا التالية:

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

بيانات البيان والأذونات

في ملف بيان تطبيقك، أعلِن أنّ تطبيقك يستخدم الإذن MANAGE_OWN_CALLS كما هو موضّح في المثال التالي:

<manifest … >
    <uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
</manifest>

لمزيد من المعلومات حول الإفصاح عن أذونات التطبيق، يُرجى الاطّلاع على الأذونات.

يجب الإعلان عن خدمة تحدّد الفئة التي تنفّذ فئة ConnectionService في تطبيقك. يتطلّب النظام الفرعي للاتصالات أن تعلن الخدمة عن إذن BIND_TELECOM_CONNECTION_SERVICE لكي تتمكّن من الربط بها. يوضّح المثال التالي كيفية تعريف الخدمة في بيان التطبيق:

<service android:name="com.example.MyConnectionService"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.ConnectionService" />
    </intent-filter>
</service>

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

تنفيذ خدمة الاتصال

يجب أن يوفّر تطبيق الاتصال تنفيذًا لفئة ConnectionService التي يمكن لنظام الاتصالات الفرعي الربط بها. يجب أن يتجاوز تنفيذ ConnectionService الطرق التالية:

onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)

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

onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

يستدعي النظام الفرعي للاتصالات هذه الطريقة عندما يستدعي تطبيقك طريقة placeCall(Uri, Bundle) ويتعذّر إجراء المكالمة الصادرة. استجابةً لهذا الموقف، يجب أن يُعلم تطبيقك المستخدم (على سبيل المثال، باستخدام مربع تنبيه أو إشعار منبثق) بأنه تعذّر إجراء المكالمة الصادرة. قد لا يتمكّن تطبيقك من إجراء مكالمة إذا كانت هناك مكالمة طوارئ جارية، أو إذا كانت هناك مكالمة جارية في تطبيق آخر لا يمكن تعليقها قبل إجراء مكالمتك.

onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest)

يستدعي النظام الفرعي للاتصالات هذه الطريقة عندما يستدعي تطبيقك طريقة addNewIncomingCall(PhoneAccountHandle, Bundle) لإبلاغ النظام بمكالمة واردة جديدة في تطبيقك. يعرض تطبيقك مثيلاً جديدًا لتنفيذ Connection (لمزيد من المعلومات، راجِع تنفيذ الاتصال) لتمثيل المكالمة الواردة الجديدة. يمكنك تخصيص الاتصال الوارد بشكل أكبر من خلال تنفيذ الإجراءات التالية:

onCreateIncomingConnectionFailed(PhoneAccountHandle, ConnectionRequest)

يستدعي النظام الفرعي للاتصالات هذه الطريقة عندما يستدعي تطبيقك طريقة addNewIncomingCall(PhoneAccountHandle, Bundle) لإبلاغ نظام الاتصالات بمكالمة واردة جديدة، ولكن المكالمة الواردة غير مسموح بها (لمزيد من المعلومات، يُرجى الاطّلاع على قيود الاتصال). يجب أن يرفض تطبيقك المكالمة الواردة بدون إصدار صوت، مع إمكانية نشر إشعار لإعلام المستخدم بالمكالمة الفائتة.

تنفيذ عملية الربط

يجب أن ينشئ تطبيقك فئة فرعية من Connection لتمثيل المكالمات في تطبيقك. يجب إلغاء الطرق التالية في عملية التنفيذ:

onShowIncomingCallUi()

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

onCallAudioStateChanged(CallAudioState)

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

onHold()

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

onUnhold()

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

onAnswer()

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

onReject()

يستدعي النظام الفرعي للاتصالات هذه الطريقة عندما يريد رفض مكالمة واردة. بعد أن يرفض تطبيقك المكالمة، عليه استدعاء setDisconnected(DisconnectCause) وتحديد REJECTED كمَعلمة. يجب أن يستدعي تطبيقك بعد ذلك طريقة destroy() لإبلاغ النظام بأنّ التطبيق قد عالج المكالمة. يستدعي النظام الفرعي للاتصالات هذه الطريقة عندما يرفض المستخدم مكالمة واردة من تطبيقك.

onDisconnect()

يستدعي النظام الفرعي للاتصالات هذه الطريقة عندما يريد قطع الاتصال بمكالمة. بعد انتهاء المكالمة، يجب أن يستدعي تطبيقك طريقة setDisconnected(DisconnectCause) ويحدّد LOCAL كمَعلمة للإشارة إلى أنّ طلب المستخدم تسبّب في قطع المكالمة. يجب أن يستدعي تطبيقك بعد ذلك طريقة destroy() لإبلاغ النظام الفرعي للاتصالات بأنّ التطبيق قد عالج المكالمة. قد يستدعي النظام هذه الطريقة عندما ينهي المستخدم مكالمة من خلال خدمة أخرى أثناء المكالمة، مثل Android Auto. يستدعي النظام أيضًا هذه الطريقة عندما يجب إنهاء مكالمتك للسماح بإجراء مكالمة أخرى، على سبيل المثال، إذا أراد المستخدم إجراء مكالمة طوارئ. لمزيد من المعلومات حول الخدمات أثناء المكالمات، يُرجى الاطّلاع على InCallService.

التعامل مع سيناريوهات الاتصال الشائعة

يتطلب استخدام واجهة برمجة التطبيقات ConnectionService في مسار المكالمات التفاعل مع الفئات الأخرى في حزمة android.telecom. توضّح الأقسام التالية سيناريوهات المكالمات الشائعة وكيفية استخدام تطبيقك لواجهات برمجة التطبيقات للتعامل معها.

الرد على المكالمات الواردة

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

ما مِن مكالمات نشطة في تطبيقات أخرى

للردّ على المكالمات الواردة في حال عدم وجود مكالمات نشطة في تطبيقات أخرى، اتّبِع الخطوات التالية:

  1. يتلقّى تطبيقك مكالمة واردة جديدة باستخدام آلياته المعتادة.
  2. استخدِم طريقة addNewIncomingCall(PhoneAccountHandle, Bundle) لإعلام النظام الفرعي للاتصالات بالمكالمة الواردة الجديدة.
  3. يرتبط النظام الفرعي للاتصالات بتنفيذ ConnectionService في تطبيقك ويطلب مثيلاً جديدًا من فئة Connection التي تمثّل المكالمة الواردة الجديدة باستخدام طريقة onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest).
  4. يُعلم النظام الفرعي للاتصالات تطبيقك بأنّه يجب عرض واجهة المستخدم للمكالمات الواردة باستخدام طريقة onShowIncomingCallUi().
  5. يعرض تطبيقك واجهة المستخدم الواردة باستخدام إشعار يتضمّن intent ملء الشاشة مرتبطًا به. لمزيد من المعلومات، يُرجى الاطّلاع على onShowIncomingCallUi().
  6. استخدِم طريقة setActive() إذا وافق المستخدم على المكالمة الواردة، أو استخدِم طريقة setDisconnected(DisconnectCause) مع تحديد REJECTED كمَعلمة، ثم استخدِم طريقة destroy() إذا رفض المستخدم المكالمة الواردة.

المكالمات النشطة في التطبيقات الأخرى التي لا يمكن تعليقها

للردّ على المكالمات الواردة عندما تكون هناك مكالمات نشطة في تطبيقات أخرى لا يمكن وضعها قيد الانتظار، اتّبِع الخطوات التالية:

  1. يتلقّى تطبيقك مكالمة واردة جديدة باستخدام آلياته المعتادة.
  2. استخدِم طريقة addNewIncomingCall(PhoneAccountHandle, Bundle) لإعلام النظام الفرعي للاتصالات بالمكالمة الواردة الجديدة.
  3. يرتبط النظام الفرعي للاتصالات بتنفيذ ConnectionService في تطبيقك ويطلب مثيلاً جديدًا لكائن Connection الذي يمثّل المكالمة الواردة الجديدة باستخدام طريقة onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest).
  4. يعرض النظام الفرعي للاتصالات واجهة مستخدم المكالمة الواردة.
  5. إذا قَبِل المستخدم المكالمة، يستدعي النظام الفرعي للاتصالات الطريقة onAnswer(). يجب استدعاء طريقة setActive() لإبلاغ النظام الفرعي للاتصالات بأنّ المكالمة متصلة الآن.
  6. إذا رفض المستخدم المكالمة، يستدعي النظام الفرعي للاتصالات الطريقة onReject(). يجب استدعاء الإجراء setDisconnected(DisconnectCause) مع تحديد REJECTED كمَعلمة، ثم استدعاء الإجراء destroy().

إجراء مكالمات صادرة

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

لإجراء مكالمة صادرة، اتّبِع الخطوات التالية:

  1. يبدأ المستخدم مكالمة صادرة داخل تطبيقك.
  2. استخدِم طريقة placeCall(Uri, Bundle) لإعلام النظام الفرعي للاتصالات بالمكالمة الصادرة الجديدة. يُرجى مراعاة ما يلي في ما يتعلق بمعلمات الطريقة:
    • تمثّل المَعلمة Uri العنوان الذي يتم إجراء المكالمة إليه. بالنسبة إلى أرقام الهواتف العادية، استخدِم مخطّط URI‏ tel:.
    • تتيح لك المَعلمة Bundle تقديم معلومات عن تطبيق الاتصال من خلال إضافة العنصر PhoneAccountHandle الخاص بتطبيقك إلى الإضافة EXTRA_PHONE_ACCOUNT_HANDLE. يجب أن يوفّر تطبيقك عنصر PhoneAccountHandle لكل مكالمة صادرة.
    • تتيح لك المَعلمة Bundle أيضًا تحديد ما إذا كانت المكالمة الصادرة تتضمّن فيديو من خلال تحديد القيمة STATE_BIDIRECTIONAL في المَعلمة الإضافية EXTRA_START_CALL_WITH_VIDEO_STATE. يُرجى العِلم أنّ النظام الفرعي للاتصالات يوجّه مكالمات الفيديو تلقائيًا إلى مكبّر الصوت.
  3. يرتبط النظام الفرعي للاتصالات بتنفيذ ConnectionService في تطبيقك.
  4. إذا لم يتمكّن تطبيقك من إجراء مكالمة صادرة، يستدعي النظام الفرعي للاتصالات الطريقة onCreateOutgoingConnectionFailed(PhoneAccountHandle, ConnectionRequest) لإبلاغ تطبيقك بأنّه لا يمكن إجراء المكالمة في الوقت الحالي. ويجب أن يُعلم تطبيقك المستخدم بأنّه لا يمكن إجراء المكالمة.
  5. إذا كان تطبيقك قادرًا على إجراء المكالمة الصادرة، يستدعي النظام الفرعي للاتصالات الدالة onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest). يجب أن يعرض تطبيقك مثيلاً لفئة Connection لتمثيل المكالمة الصادرة الجديدة. لمزيد من المعلومات حول السمات التي يجب ضبطها في الاتصال، يُرجى الاطّلاع على تنفيذ خدمة الاتصال.
  6. عندما يتم ربط المكالمة الصادرة، يمكنك استدعاء طريقة setActive() لإعلام النظام الفرعي للاتصالات بأن المكالمة نشطة.

إنهاء مكالمة

لإنهاء مكالمة، اتّبِع الخطوات التالية:

  1. يجب استدعاء الدالة setDisconnected(DisconnectCause) وإرسال المَعلمة LOCAL إذا أنهى المستخدم المكالمة، أو إرسال المَعلمة REMOTE إذا أنهى الطرف الآخر المكالمة.
  2. استدعِ طريقة destroy().

قيود الاتصال

لضمان تجربة اتصال متسقة وبسيطة للمستخدمين، يفرض إطار عمل الاتصالات بعض القيود لإدارة المكالمات على الجهاز. على سبيل المثال، لنفترض أنّ المستخدم ثبَّت تطبيقَي اتصال يستخدمان واجهة برمجة التطبيقات ConnectionService المُدارة ذاتيًا، وهما FooTalk وBarTalk. في هذه الحالة، تنطبق القيود التالية:

  • على الأجهزة التي تعمل بمستوى واجهة برمجة التطبيقات 27 أو أقل، يمكن لتطبيق واحد فقط إجراء مكالمة جارية في أي وقت. يعني هذا القيد أنّه عندما يكون لدى المستخدم مكالمة جارية باستخدام تطبيق FooTalk، لا يمكن لتطبيق BarTalk بدء مكالمة جديدة أو تلقّيها.

    على الأجهزة التي تعمل بالمستوى 28 أو أعلى من واجهة برمجة التطبيقات، إذا أعلن كل من FooTalk وBarTalk عن CAPABILITY_SUPPORT_HOLD و CAPABILITY_HOLD الأذونات، يمكن للمستخدم إجراء أكثر من مكالمة جارية من خلال التبديل بين التطبيقات لبدء مكالمة أخرى أو الرد عليها.

  • إذا كان المستخدم يجري مكالمات عادية مُدارة (على سبيل المثال، باستخدام تطبيق "الهاتف" أو "برنامج الاتصال" المدمج)، لا يمكنه إجراء مكالمات من تطبيقات الاتصال. وهذا يعني أنّه إذا كان المستخدم يجري مكالمة عادية باستخدام مشغّل شبكة الجوّال، لا يمكنه أيضًا إجراء مكالمة FooTalk أو BarTalk في الوقت نفسه.

  • يقطع النظام الفرعي للاتصالات مكالمات تطبيقك إذا طلب المستخدم مكالمة طوارئ.

  • لا يمكن لتطبيقك تلقّي مكالمات أو إجراؤها أثناء إجراء المستخدم مكالمة طوارئ.

  • إذا كانت هناك مكالمة جارية في تطبيق اتصال آخر عندما يتلقّى تطبيقك مكالمة واردة، فإنّ الردّ على المكالمة الواردة يؤدي إلى إنهاء أي مكالمات جارية في التطبيق الآخر. يجب ألا يعرض تطبيقك واجهة المستخدم المعتادة للمكالمات الواردة. يعرض إطار عمل الاتصالات واجهة مستخدم المكالمة الواردة ويُعلم المستخدم بأنّ الرد على المكالمة الجديدة سيؤدي إلى إنهاء مكالماته الجارية. وهذا يعني أنّه إذا كان المستخدم يجري مكالمة على FooTalk وتلقّى تطبيق BarTalk مكالمة واردة، سيُعلم إطار عمل الاتصالات المستخدم بأنّ لديه مكالمة واردة جديدة على BarTalk وأنّ الرد على مكالمة BarTalk سيؤدي إلى إنهاء مكالمة FooTalk.

ضبط التطبيق كتطبيق الهاتف التلقائي

تطبيق الاتصال/الهاتف التلقائي هو التطبيق الذي يوفّر واجهة المستخدم أثناء المكالمة عندما يكون الجهاز في مكالمة. ويوفّر أيضًا للمستخدم وسيلة لبدء المكالمات والاطّلاع على سجلّ المكالمات على جهازه. يأتي الجهاز مزوّدًا بتطبيق اتصال/هاتف تلقائي يوفّره النظام. ويمكن للمستخدم اختيار تطبيق واحد لتولّي هذا الدور بدلاً من تطبيق النظام. يستخدم التطبيق الذي يرغب في تولّي هذا الدور RoleManager لطلب تولّي دور RoleManager.ROLE_DIALER.

يوفّر تطبيق الهاتف التلقائي واجهة مستخدم أثناء إجراء مكالمة على الجهاز، ولا يكون الجهاز في وضع السيارة (أي أنّ UiModeManager#getCurrentModeType() ليس Configuration.UI_MODE_TYPE_CAR).

لكي يؤدي التطبيق دور RoleManager.ROLE_DIALER، يجب أن يستوفي عددًا من المتطلبات:

  • يجب أن يعالج الطلب Intent#ACTION_DIAL. وهذا يعني أنّ التطبيق يجب أن يوفّر واجهة مستخدم للوحة الاتصال تتيح للمستخدم إجراء المكالمات الصادرة.
  • يجب أن تنفّذ واجهة برمجة التطبيقات InCallService بالكامل وأن توفّر واجهة مستخدم للمكالمات الواردة وواجهة مستخدم للمكالمات الجارية.

سيتم دائمًا استخدام برنامج الاتصال المُحمَّل مسبقًا عندما يجري المستخدم مكالمة طوارئ، حتى إذا كان تطبيقك يشغل دور RoleManager.ROLE_DIALER. لضمان الحصول على أفضل تجربة عند إجراء مكالمة طوارئ، يجب أن يستخدم برنامج الاتصال التلقائي دائمًا TelecomManager.placeCall(Uri, Bundle) لإجراء المكالمات (بما في ذلك مكالمات الطوارئ). يضمن ذلك أن يتمكّن النظام الأساسي من التحقّق من أنّ الطلب وارد من برنامج الاتصال التلقائي. إذا كان تطبيق الاتصال غير المُحمَّل مسبقًا يستخدم Intent#ACTION_CALL لإجراء مكالمة طوارئ، سيتم رفعه إلى تطبيق الاتصال المُحمَّل مسبقًا باستخدام Intent#ACTION_DIAL للتأكيد، وهذا لا يوفّر تجربة مثالية للمستخدم.

في ما يلي مثال على تسجيل بيان لـ InCallService. تشير البيانات الوصفية TelecomManager#METADATA_IN_CALL_SERVICE_UI إلى أنّ عملية تنفيذ InCallService هذه تهدف إلى استبدال واجهة المستخدم المضمّنة أثناء المكالمة. تشير البيانات الوصفية TelecomManager#METADATA_IN_CALL_SERVICE_RINGING إلى أنّ هذا InCallService سيشغّل نغمة الرنين للمكالمات الواردة. يُرجى الاطّلاع على القسم أدناه لمعرفة المزيد من المعلومات عن عرض واجهة مستخدم المكالمات الواردة وتشغيل نغمة الرنين في تطبيقك.

 <service android:name="your.package.YourInCallServiceImplementation"
          android:permission="android.permission.BIND_INCALL_SERVICE"
          android:exported="true">
      <meta-data android:name="android.telecom.IN_CALL_SERVICE_UI" android:value="true" />
      <meta-data android:name="android.telecom.IN_CALL_SERVICE_RINGING"
          android:value="true" />
      <intent-filter>
          <action android:name="android.telecom.InCallService"/>
      </intent-filter>
 </service>

ملاحظة: يجب عدم وضع علامة على InCallService باستخدام السمة android:exported="false"، لأنّ ذلك قد يؤدي إلى تعذُّر الربط بالتنفيذ أثناء المكالمات.

بالإضافة إلى تنفيذ واجهة برمجة التطبيقات InCallService، يجب أيضًا الإعلان عن نشاط في ملف البيان الخاص بك يعالج الغرض Intent#ACTION_DIAL. يوضح المثال أدناه كيفية إجراء ذلك:

 <activity android:name="your.package.YourDialerActivity"
           android:label="@string/yourDialerActivityLabel">
      <intent-filter>
           <action android:name="android.intent.action.DIAL" />
           <category android:name="android.intent.category.DEFAULT" />
      </intent-filter>
      <intent-filter>
           <action android:name="android.intent.action.DIAL" />
           <category android:name="android.intent.category.DEFAULT" />
           <data android:scheme="tel" />
      </intent-filter>
 </activity>

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

يوضّح الرمز أدناه كيف يمكن لتطبيقك طلب أن يصبح تطبيق الهاتف/الاتصال التلقائي:

 private static final int REQUEST_ID = 1;

 public void requestRole() {
     RoleManager roleManager = (RoleManager) getSystemService(ROLE_SERVICE);
     Intent intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_DIALER);
     startActivityForResult(intent, REQUEST_ID);
 }

 public void onActivityResult(int requestCode, int resultCode, Intent data) {
     if (requestCode == REQUEST_ID) {
         if (resultCode == android.app.Activity.RESULT_OK) {
             // Your app is now the default dialer app
         } else {
             // Your app is not the default dialer app
         }
     }
 }

الوصول إلى InCallService للأجهزة القابلة للارتداء

إذا كان تطبيقك مصاحبًا تابعًا لجهة خارجية ويريد الوصول إلى واجهات برمجة تطبيقات InCallService، فيمكنه إجراء ما يلي:

  1. تضمين إذن MANAGE_ONGOING_CALLS في بيان تطبيقك
  2. الربط بجهاز فعلي قابل للارتداء من خلال واجهة برمجة التطبيقات CompanionDeviceManager كتطبيق مصاحب (يُرجى الاطّلاع على إقران الجهاز المصاحب)
  3. يجب تنفيذ واجهة InCallService هذه باستخدام إذن BIND_INCALL_SERVICE

عرض إشعار المكالمة الواردة

عندما يتلقّى تطبيقك مكالمة واردة جديدة عبر InCallService#onCallAdded(Call)، يكون مسؤولاً عن عرض واجهة مستخدم للمكالمة الواردة. ويجب أن يتم ذلك باستخدام واجهات برمجة تطبيقات NotificationManager لنشر إشعار جديد بشأن مكالمة واردة.

عندما يعلن تطبيقك عن البيانات الوصفية TelecomManager#METADATA_IN_CALL_SERVICE_RINGING، يكون مسؤولاً عن تشغيل نغمة الرنين للمكالمات الواردة. يجب أن ينشئ تطبيقك NotificationChannel يحدّد نغمة الرنين المطلوبة. على سبيل المثال:

 NotificationChannel channel = new NotificationChannel(YOUR_CHANNEL_ID, "Incoming Calls",
          NotificationManager.IMPORTANCE_MAX);
 // other channel setup stuff goes here.

 // We'll use the default system ringtone for our incoming call notification channel.  You can
 // use your own audio resource here.
 Uri ringtoneUri = RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE);
 channel.setSound(ringtoneUri, new AudioAttributes.Builder()
          // Setting the AudioAttributes is important as it identifies the purpose of your
          // notification sound.
          .setUsage(AudioAttributes.USAGE_NOTIFICATION_RINGTONE)
          .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
      .build());

 NotificationManager mgr = getSystemService(NotificationManager.class);
 mgr.createNotificationChannel(channel);

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

 // Create an intent which triggers your fullscreen incoming call user interface.
 Intent intent = new Intent(Intent.ACTION_MAIN, null);
 intent.setFlags(Intent.FLAG_ACTIVITY_NO_USER_ACTION | Intent.FLAG_ACTIVITY_NEW_TASK);
 intent.setClass(context, YourIncomingCallActivity.class);
 PendingIntent pendingIntent = PendingIntent.getActivity(context, 1, intent, PendingIntent.FLAG_MUTABLE_UNAUDITED);
 // Build the notification as an ongoing high priority item; this ensures it will show as
 // a heads up notification which slides down over top of the current content.
 final Notification.Builder builder = new Notification.Builder(context);
 builder.setOngoing(true);
 builder.setPriority(Notification.PRIORITY_HIGH);
 // Set notification content intent to take user to the fullscreen UI if user taps on the
 // notification body.
 builder.setContentIntent(pendingIntent);
 // Set full screen intent to trigger display of the fullscreen UI when the notification
 // manager deems it appropriate.
 builder.setFullScreenIntent(pendingIntent, true);
 // Setup notification content.
 builder.setSmallIcon( yourIconResourceId );
 builder.setContentTitle("Your notification title");
 builder.setContentText("Your notification content.");
 // Use builder.addAction(..) to add buttons to answer or reject the call.
 NotificationManager notificationManager = mContext.getSystemService(
     NotificationManager.class);
 notificationManager.notify(YOUR_CHANNEL_ID, YOUR_TAG, YOUR_ID, builder.build());
```