نظرة عامة على إطار عمل الاتصالات

يدير إطار عمل الاتصالات في Android (المعروف أيضًا باسم "الاتصالات") المكالمات الصوتية والفيديو على جهاز Android. ويشمل ذلك المكالمات المستندة إلى شريحة SIM، مثل المكالمات التي تستخدم إطار عمل خدمات الهاتف، ومكالمات بروتوكول الإنترنت الصوتي (VoIP) التي تنفِّذ مكتبة Core-Telecom Jetpack.

المكونات الرئيسية التي تديرها شركة Telecom هي ConnectionService و InCallService.

يعتمد تنفيذ ConnectionService على تقنيات مثل شبكة الهاتف العام (PSTN) لربط المكالمات بجهات أخرى. إنّ ConnectionService الأكثر شيوعًا على الهاتف هو ConnectionService الهاتفي. يربط المكالمات التي تتم من خلال مشغّل شبكة الجوّال.

يقدّم تطبيق InCallService واجهة مستخدم للمكالمات التي تديرها شركة Telecom، ويسمح للمستخدم بالتحكم في هذه المكالمات والتفاعل معها. إنّ الطريقة الأكثر شيوعًا لتنفيذ InCallService هي تطبيق الهاتف المُدمَج مع الجهاز.

تعمل الاتصالات السلكية واللاسلكية كمركز اتصالات. وتعمل هذه الميزة على توجيه المكالمات التي تقدّمها عمليات ConnectionService التنفيذ إلى واجهات المستخدم التي تقدّمها عمليات InCallService التنفيذ.

قد تحتاج إلى تنفيذ واجهات برمجة تطبيقات Telecom API للأسباب التالية:

إنشاء تطبيق بديل للهاتف

لإنشاء بديل لتطبيق الهاتف التلقائي على جهاز Android، نفِّذ واجهة برمجة التطبيقات InCallService. يجب أن يستوفي التنفيذ المتطلّبات التالية:

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

لمزيد من المعلومات، يُرجى الاطّلاع على InCallService.

دمج حلّ اتصال

لدمج حلّ الاتصال في Android، لديك الخيارات التالية:

  • تنفيذ مكتبة Core-Telecom Jetpack المُدارة ذاتيًا: هذا الخيار مثالي لمطوّري تطبيقات الاتصال المستقلة الذين لا يريدون عرض مكالماتهم ضمن تطبيق الهاتف التلقائي، ولا يريدون أيضًا عرض مكالمات أخرى في واجهة المستخدم.

    عند الدمج مع مكتبة Core-Telecom Jetpack، تساعد تطبيقك على التفاعل ليس فقط مع الاتصال الهاتفي للنظام على الجهاز، ولكن أيضًا مع تطبيقات الاتصال المستقلة الأخرى التي يتم دمجها مع Telecom. تدير مكتبة Core-Telecom أيضًا توجيه الصوت والتركيز عليه. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة إنشاء تطبيق اتصال.

  • تنفيذ واجهة برمجة التطبيقات ConnectionService API المُدارة: يسهّل هذا الخيار تطوير حلّ اتصال يعتمد على تطبيق الهاتف الحالي على الجهاز لتوفير واجهة المستخدم للمكالمات. وتشمل الأمثلة خدمات اتصالات SIP وVoIP التي تنفذها جهة خارجية. لمزيد من التفاصيل، يُرجى الاطّلاع على getDefaultDialerPackage().

    لا توفّر ConnectionService وحدها سوى وسائل ربط المكالمات. ليس لديه واجهة مستخدم مرتبطة.

  • تنفيذ كلّ من واجهتَي برمجة التطبيقات InCallService وConnectionService: هذا الخيار مثالي إذا كنت تريد إنشاء حلّ اتصال خاص بك يستند إلى ConnectionService، مع واجهة مستخدم خاصة به، وعرض جميع مكالمات Android الأخرى في واجهة المستخدم نفسها. عند استخدام هذا النهج، يجب ألا يؤدي تنفيذ InCallService إلى إجراء أي افتراضات حول مصادر المكالمات التي يعرضها. يجب أيضًا أن يستمر تنفيذ ConnectionService بدون ضبط تطبيق الهاتف التلقائي على InCallService المخصّص.

تصفية المكالمات

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

إذا كنت تستخدم CallScreeningService تنفيذًا لفحص المكالمات استدعاء الدالة onScreenCall() لأي مكالمات واردة أو صادرة جديدة عندما لا يكون الرقم مُدرَجًا في قائمة جهات اتصال المستخدم يمكنك التحقّق من عنصر Call.Details للحصول على معلومات حول المكالمة. على وجه التحديد، تتضمّن الدالة getCallerNumberVerificationStatus() معلومات من مقدّم الشبكة عن الرقم الآخر. إذا تعذّر إثبات ملكية الرقم، هذا مؤشر جيد على أنّ المكالمة تأتي من رقم غير صالح أو من متصل غير مرغوب فيه.

Kotlin

class ScreeningService : CallScreeningService() {
    // This function is called when an ingoing or outgoing call
    // is from a number not in the user's contacts list
    override fun onScreenCall(callDetails: Call.Details) {
        // Can check the direction of the call
        val isIncoming = callDetails.callDirection == Call.Details.DIRECTION_INCOMING

        if (isIncoming) {
            // the handle (e.g. phone number) that the Call is currently connected to
            val handle: Uri = callDetails.handle

            // determine if you want to allow or reject the call
            when (callDetails.callerNumberVerificationStatus) {
                Connection.VERIFICATION_STATUS_FAILED -> {
                    // Network verification failed, likely an invalid/spam call.
                }
                Connection.VERIFICATION_STATUS_PASSED -> {
                    // Network verification passed, likely a valid call.
                }
                else -> {
                    // Network could not perform verification.
                    // This branch matches Connection.VERIFICATION_STATUS_NOT_VERIFIED.
                }
            }
        }
    }
}

Java

class ScreeningService extends CallScreeningService {
    @Override
    public void onScreenCall(@NonNull Call.Details callDetails) {
        boolean isIncoming = callDetails.getCallDirection() == Call.Details.DIRECTION_INCOMING;

        if (isIncoming) {
            Uri handle = callDetails.getHandle();

            switch (callDetails.getCallerNumberVerificationStatus()) {
                case Connection.VERIFICATION_STATUS_FAILED:
                    // Network verification failed, likely an invalid/spam call.
                    break;
                case Connection.VERIFICATION_STATUS_PASSED:
                    // Network verification passed, likely a valid call.
                    break;
                default:
                    // Network could not perform verification.
                    // This branch matches Connection.VERIFICATION_STATUS_NOT_VERIFIED
            }
        }
    }
}

اضبط الدالة onScreenCall() على الاتصال respondToCall() لإخبار النظام بكيفية الردّ على المكالمة الجديدة. تأخذ هذه الدالة مَعلمة CallResponse يمكنك استخدامها لإخبار النظام بحظر المكالمة أو رفضها كما لو كان المستخدم هو من فعل ذلك أو كتم صوتها. يمكنك أيضًا أن تطلب من النظام تخطّي إضافة هذه المكالمة إلى سجلّ المكالمات على الجهاز.

Kotlin

// Tell the system how to respond to the incoming call
// and if it should notify the user of the call.
val response = CallResponse.Builder()
    // Sets whether the incoming call should be blocked.
    .setDisallowCall(false)
    // Sets whether the incoming call should be rejected as if the user did so manually.
    .setRejectCall(false)
    // Sets whether ringing should be silenced for the incoming call.
    .setSilenceCall(false)
    // Sets whether the incoming call should not be displayed in the call log.
    .setSkipCallLog(false)
    // Sets whether a missed call notification should not be shown for the incoming call.
    .setSkipNotification(false)
    .build()

// Call this function to provide your screening response.
respondToCall(callDetails, response)

Java

// Tell the system how to respond to the incoming call
// and if it should notify the user of the call.
CallResponse.Builder response = new CallResponse.Builder();
// Sets whether the incoming call should be blocked.
response.setDisallowCall(false);
// Sets whether the incoming call should be rejected as if the user did so manually.
response.setRejectCall(false);
// Sets whether ringing should be silenced for the incoming call.
response.setSilenceCall(false);
// Sets whether the incoming call should not be displayed in the call log.
response.setSkipCallLog(false);
// Sets whether a missed call notification should not be shown for the incoming call.
response.setSkipNotification(false);

// Call this function to provide your screening response.
respondToCall(callDetails, response.build());

يجب تسجيل عملية تنفيذ CallScreeningService في ملف البيان باستخدام فلتر الأهداف والإذن المناسبَين ليتمكّن النظام من بدء تنفيذها بشكل صحيح.

<service
    android:name=".ScreeningService"
    android:permission="android.permission.BIND_SCREENING_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallScreeningService" />
    </intent-filter>
</service>

إعادة توجيه مكالمة

تدير الأجهزة التي تعمل بنظام التشغيل Android 10 أو إصدار أحدث نوايا المكالمات بشكل مختلف عن الأجهزة التي تعمل بنظام التشغيل Android 9 أو إصدار أقدم. في الإصدار 10 من نظام Android والإصدارات الأحدث، تم إيقاف واجهة برمجة التطبيقات ACTION_NEW_OUTGOING_CALL البث نهائيًا واستبدالها بواجهة برمجة التطبيقات CallRedirectionService. يوفّر CallRedirectionService واجهات يمكنك استخدامها لتعديل المكالمات الصادرة التي تجريها منصة Android. على سبيل المثال، قد تلغي التطبيقات التابعة لجهات خارجية المكالمات وتعيد توجيهها عبر بروتوكول نقل الصوت على الإنترنت (VoIP).

Kotlin

class RedirectionService : CallRedirectionService() {
    override fun onPlaceCall(
        handle: Uri,
        initialPhoneAccount: PhoneAccountHandle,
        allowInteractiveResponse: Boolean
    ) {
        // Determine if the call should proceed, be redirected, or cancelled.
        val callShouldProceed = true
        val callShouldRedirect = false
        when {
            callShouldProceed -> {
                placeCallUnmodified()
            }
            callShouldRedirect -> {
                // Update the URI to point to a different phone number or modify the
                // PhoneAccountHandle and redirect.
                redirectCall(handle, initialPhoneAccount, true)
            }
            else -> {
                cancelCall()
            }
        }
    }
}

Java

class RedirectionService extends CallRedirectionService {
    @Override
    public void onPlaceCall(
            @NonNull Uri handle,
            @NonNull PhoneAccountHandle initialPhoneAccount,
            boolean allowInteractiveResponse
    ) {
        // Determine if the call should proceed, be redirected, or cancelled.
        // Your app should implement this logic to determine the redirection.
        boolean callShouldProceed = true;
        boolean callShouldRedirect = false;
        if (callShouldProceed) {
            placeCallUnmodified();
        } else if (callShouldRedirect) {
            // Update the URI to point to a different phone number or modify the
            // PhoneAccountHandle and redirect.
            redirectCall(handle, initialPhoneAccount, true);
        } else {
            cancelCall();
        }
    }
}

يجب تسجيل هذه الخدمة في البيان لكي يتمكّن النظام من بدؤها بشكل صحيح.

<service
    android:name=".RedirectionService"
    android:permission="android.permission.BIND_CALL_REDIRECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.CallRedirectionService"/>
    </intent-filter>
</service>

لاستخدام خدمة إعادة التوجيه، يجب أن يطلب تطبيقك دور إعادة توجيه المكالمات من RoleManager. سيُطلب من العميل تحديد ما إذا كان يريد السماح لتطبيقك بمعالجة عمليات إعادة توجيه المكالمات. إذا لم يتم منح تطبيقك هذا الدور، لن يتم استخدام خدمة إعادة التوجيه.

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

Kotlin

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Tell the system that you want your app to handle call redirects. This
        // is done by using the RoleManager to register your app to handle redirects.
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
            val roleManager = getSystemService(Context.ROLE_SERVICE) as RoleManager
            // Check if the app needs to register call redirection role.
            val shouldRequestRole = roleManager.isRoleAvailable(RoleManager.ROLE_CALL_REDIRECTION) &&
                    !roleManager.isRoleHeld(RoleManager.ROLE_CALL_REDIRECTION)
            if (shouldRequestRole) {
                val intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_REDIRECTION)
                startActivityForResult(intent, REDIRECT_ROLE_REQUEST_CODE)
            }
        }
    }

    companion object {
        private const val REDIRECT_ROLE_REQUEST_CODE = 1
    }
}

Java

class MainActivity extends AppCompatActivity {
    private static final int REDIRECT_ROLE_REQUEST_CODE = 0;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Tell the system that you want your app to handle call redirects. This
        // is done by using the RoleManager to register your app to handle redirects.
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
            RoleManager roleManager = (RoleManager) getSystemService(Context.ROLE_SERVICE);
            // Check if the app needs to register call redirection role.
            boolean shouldRequestRole = roleManager.isRoleAvailable(RoleManager.ROLE_CALL_REDIRECTION) &&
                    !roleManager.isRoleHeld(RoleManager.ROLE_CALL_REDIRECTION);
            if (shouldRequestRole) {
                Intent intent = roleManager.createRequestRoleIntent(RoleManager.ROLE_CALL_REDIRECTION);
                startActivityForResult(intent, REDIRECT_ROLE_REQUEST_CODE);
            }
        }
    }
}