‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

جفت‌سازی دستگاه همپا

در دستگاه‌هایی که Android نسخه ۸.۰ (سطح میانای برنامه‌سازی کاربردی ۲۶) و بالاتر را اجرا می‌کنند، جفت‌سازی دستگاه همپا اسکن بلوتوث یا Wi-Fi دستگاه‌های اطراف را ازطرف برنامه شما بدون نیاز به اجازه ACCESS_FINE_LOCATION انجام می‌دهد. این کار به حداکثر رساندن محافظت از حریم خصوصی کاربر کمک می‌کند. از این روش برای انجام پیکربندی اولیه دستگاه همپا، مانند ساعت هوشمند سازگار با BLE، استفاده کنید. علاوه‌براین، جفت‌سازی دستگاه همپا مستلزم فعال بودن «خدمات مکان» است.

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

پس‌از جفت شدن دستگاه، دستگاه می‌تواند از اجازه‌های REQUEST_COMPANION_RUN_IN_BACKGROUND و REQUEST_COMPANION_USE_DATA_IN_BACKGROUND برای راه‌اندازی برنامه از پس‌زمینه استفاده کند. برنامه‌ها همچنین می‌توانند از اجازه REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND برای راه‌اندازی سرویس پیش‌زمینه‌ای از پس‌زمینه استفاده کنند.

کاربر می‌تواند دستگاهی را از فهرست انتخاب کند و به برنامه اجازه دهد به دستگاه دسترسی داشته باشد. اگر برنامه را حذف نصب کنید یا disassociate() را فراخوانی کنید، این اجازه‌ها لغو می‌شوند. برنامه همپا مسئول پاک کردن تداعی‌های خود است، اگر کاربر دیگر به آن‌ها نیاز نداشته باشد، مثلاً وقتی از سیستم خارج می‌شود یا دستگاه‌های محدودشده را برمی‌دارد.

پیاده‌سازی جفت‌سازی دستگاه همپا

این بخش توضیح می‌دهد که چگونه از CompanionDeviceManager برای جفت کردن برنامه با دستگاه‌های همپا ازطریق بلوتوث، BLE، و Wi-Fi استفاده کنید.

مشخص کردن دستگاه‌های همپا

نمونه کد زیر نحوه افزودن پرچم <uses-feature> به فایل مانیفست را نشان می‌دهد. این کار به سیستم می‌گوید که برنامه شما قصد دارد دستگاه‌های همپا را راه‌اندازی کند.

<uses-feature android:name="android.software.companion_device_setup"/>

فهرست کردن دستگاه‌ها براساس `DeviceFilter`

می‌توانید همه دستگاه‌های همپای موجود در محدوده را که با DeviceFilter ارائه‌شده مطابقت دارند نمایش دهید (در شکل ۱ نشان داده شده است). اگر می‌خواهید اسکن را فقط به یک دستگاه محدود کنید، می‌توانید setSingleDevice() را به true تغییر دهید (در شکل ۲ نشان داده شده است).

جفت‌سازی تک‌دستگاهی — **شکل ۲.** جفت‌سازی تک‌دستگاهه

موارد زیر زیرکلاس‌های DeviceFilter هستند که می‌توانند در AssociationRequest مشخص شوند:

هر سه زیرکلاس دارای سازنده‌هایی هستند که پیکربندی فیلترها را ساده می‌کنند. در مثال زیر، دستگاهی دستگاه بلوتوثی را با BluetoothDeviceFilter اسکن می‌کند.

کاتلین

val deviceFilter: BluetoothDeviceFilter = BluetoothDeviceFilter.Builder()
        // Match only Bluetooth devices whose name matches the pattern.
        .setNamePattern(Pattern.compile("My device"))
        // Match only Bluetooth devices whose service UUID matches this pattern.
        .addServiceUuid(ParcelUuid(UUID(0x123abcL, -1L)), null)
        .build()

جاوا

BluetoothDeviceFilter deviceFilter = new BluetoothDeviceFilter.Builder()
        // Match only Bluetooth devices whose name matches the pattern.
        .setNamePattern(Pattern.compile("My device"))
        // Match only Bluetooth devices whose service UUID matches this pattern.
        .addServiceUuid(new ParcelUuid(new UUID(0x123abcL, -1L)), null)
        .build();

DeviceFilter را روی AssociationRequest تنظیم کنید تا CompanionDeviceManager بتواند تعیین کند چه نوع دستگاه‌هایی را جستجو کند.

کاتلین

val pairingRequest: AssociationRequest = AssociationRequest.Builder()
        // Find only devices that match this request filter.
        .addDeviceFilter(deviceFilter)
        // Stop scanning as soon as one device matching the filter is found.
        .setSingleDevice(true)
        .build()

جاوا

AssociationRequest pairingRequest = new AssociationRequest.Builder()
        // Find only devices that match this request filter.
        .addDeviceFilter(deviceFilter)
        // Stop scanning as soon as one device matching the filter is found.
        .setSingleDevice(true)
        .build();

پس‌از اینکه برنامه‌تان AssociationRequest را مقداردهی اولیه کرد، تابع associate() را در CompanionDeviceManager اجرا کنید. تابع associate() AssociationRequest و Callback را می‌گیرد.

Callback IntentSender را در onAssociationPending برمی‌گرداند وقتی CompanionDeviceManager دستگاهی را پیدا می‌کند و آماده است تا کادر گفتگوی رضایت کاربر را راه‌اندازی کند. پس‌از اینکه کاربر دستگاه را تأیید کرد، AssociationInfo دستگاه در onAssociationCreated برگردانده می‌شود. اگر برنامه‌تان هیچ دستگاهی پیدا نکند، فراخوانی برگشتی onFailure را با پیام خطا برمی‌گرداند.

در دستگاه‌هایی که Android 13 (سطح میانای برنامه‌سازی کاربردی ۳۳) و بالاتر را اجرا می‌کنند:

کاتلین

val deviceManager =
  requireContext().getSystemService(Context.COMPANION_DEVICE_SERVICE)

val executor: Executor =  Executor { it.run() }

deviceManager.associate(pairingRequest,
    executor,
    object : CompanionDeviceManager.Callback() {
    // Called when a device is found. Launch the IntentSender so the user
    // can select the device they want to pair with.
    override fun onAssociationPending(intentSender: IntentSender) {
        intentSender?.let {
             startIntentSenderForResult(it, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0)
        }
    }

    override fun onAssociationCreated(associationInfo: AssociationInfo) {
        // An association is created.
    }

    override fun onFailure(errorMessage: CharSequence?) {
        // To handle the failure.
     }
})

جاوا

CompanionDeviceManager deviceManager =
        (CompanionDeviceManager) getSystemService(Context.COMPANION_DEVICE_SERVICE);

Executor executor = new Executor() {
            @Override
            public void execute(Runnable runnable) {
                runnable.run();
            }
        };
deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() {
    executor,
    // Called when a device is found. Launch the IntentSender so the user can
    // select the device they want to pair with.
    @Override
    public void onDeviceFound(IntentSender chooserLauncher) {
        try {
            startIntentSenderForResult(
                    chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0
            );
        } catch (IntentSender.SendIntentException e) {
            Log.e("MainActivity", "Failed to send intent");
        }
    }

    @Override
    public void onAssociationCreated(AssociationInfo associationInfo) {
        // An association is created.
    }

    @Override
    public void onFailure(CharSequence errorMessage) {
        // To handle the failure.
    });

در دستگاه‌هایی که Android 12L (سطح میانای برنامه‌سازی کاربردی ۳۲) یا پایین‌تر (منسوخ‌شده) را اجرا می‌کنند:

کاتلین

val deviceManager =
      requireContext().getSystemService(Context.COMPANION_DEVICE_SERVICE)

deviceManager.associate(pairingRequest,
    object : CompanionDeviceManager.Callback() {
        // Called when a device is found. Launch the IntentSender so the user
        // can select the device they want to pair with.
        override fun onDeviceFound(chooserLauncher: IntentSender) {
            startIntentSenderForResult(chooserLauncher,
                SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0)
        }

        override fun onFailure(error: CharSequence?) {
            // To handle the failure.
        }
    }, null)

جاوا

CompanionDeviceManager deviceManager =
        (CompanionDeviceManager) getSystemService(Context.COMPANION_DEVICE_SERVICE);
deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() {
    // Called when a device is found. Launch the IntentSender so the user can
    // select the device they want to pair with.
    @Override
    public void onDeviceFound(IntentSender chooserLauncher) {
        try {
            startIntentSenderForResult(
                    chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0
            );
        } catch (IntentSender.SendIntentException e) {
            Log.e("MainActivity", "Failed to send intent");
        }
    }

    @Override
    public void onFailure(CharSequence error) {
        // To handle the failure.
    }
}, null);

نتیجه انتخاب کاربر به قطعه در onActivityResult() فعالیت شما ارسال می‌شود. سپس می‌توانید به دستگاه انتخاب‌شده دسترسی پیدا کنید.

وقتی کاربر دستگاه بلوتوثی را انتخاب می‌کند، منتظر BluetoothDevice باشید. وقتی کاربر دستگاه «بلوتوث کم‌مصرف» را انتخاب می‌کند، منتظر android.bluetooth.le.ScanResult باشید. وقتی کاربر دستگاه Wi-Fi را انتخاب می‌کند، انتظار android.net.wifi.ScanResult را داشته باشید.

کاتلین

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    when (requestCode) {
        SELECT_DEVICE_REQUEST_CODE -> when(resultCode) {
            Activity.RESULT_OK -> {
                // The user chose to pair the app with a Bluetooth device.
                val deviceToPair: BluetoothDevice? =
data?.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE)
                deviceToPair?.let { device ->
                    device.createBond()
                    // Continue to interact with the paired device.
                }
            }
        }
        else -> super.onActivityResult(requestCode, resultCode, data)
    }
}

جاوا

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (resultCode != Activity.RESULT_OK) {
        return;
    }
    if (requestCode == SELECT_DEVICE_REQUEST_CODE && data != null) {
        BluetoothDevice deviceToPair =
data.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE);
        if (deviceToPair != null) {
            deviceToPair.createBond();
            // Continue to interact with the paired device.
        }
    } else {
        super.onActivityResult(requestCode, resultCode, data);
    }
}

نمونه کامل را ببینید:

در دستگاه‌هایی که Android 13 (سطح میانای برنامه‌سازی کاربردی ۳۳) و بالاتر را اجرا می‌کنند:

کاتلین

private const val SELECT_DEVICE_REQUEST_CODE = 0

class MainActivity : AppCompatActivity() {

    private val deviceManager: CompanionDeviceManager by lazy {
        getSystemService(Context.COMPANION_DEVICE_SERVICE) as CompanionDeviceManager
    }
    val mBluetoothAdapter: BluetoothAdapter by lazy {
        val java = BluetoothManager::class.java
        getSystemService(java)!!.adapter }
    val executor: Executor =  Executor { it.run() }

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

        // To skip filters based on names and supported feature flags (UUIDs),
        // omit calls to setNamePattern() and addServiceUuid()
        // respectively, as shown in the following  Bluetooth example.
        val deviceFilter: BluetoothDeviceFilter = BluetoothDeviceFilter.Builder()
            .setNamePattern(Pattern.compile("My device"))
            .addServiceUuid(ParcelUuid(UUID(0x123abcL, -1L)), null)
            .build()

        // The argument provided in setSingleDevice() determines whether a single
        // device name or a list of them appears.
        val pairingRequest: AssociationRequest = AssociationRequest.Builder()
            .addDeviceFilter(deviceFilter)
            .setSingleDevice(true)
            .build()

        // When the app tries to pair with a Bluetooth device, show the
        // corresponding dialog box to the user.
        deviceManager.associate(pairingRequest,
            executor,
            object : CompanionDeviceManager.Callback() {
                // Called when a device is found. Launch the IntentSender so the user
                // can select the device they want to pair with.
                override fun onAssociationPending(intentSender: IntentSender) {
                intentSender?.let {
                    startIntentSenderForResult(it, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0)
              }
            }

             override fun onAssociationCreated(associationInfo: AssociationInfo) {
                 // AssociationInfo object is created and get association id and the
                 // macAddress.
                 var associationId: int = associationInfo.id
                 var macAddress: MacAddress = associationInfo.deviceMacAddress
             }
             override fun onFailure(errorMessage: CharSequence?) {
                // Handle the failure.
            }
    )

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        when (requestCode) {
            SELECT_DEVICE_REQUEST_CODE -> when(resultCode) {
                Activity.RESULT_OK -> {
                    // The user chose to pair the app with a Bluetooth device.
                    val deviceToPair: BluetoothDevice? =
                        data?.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE)
                    deviceToPair?.let { device ->
                        device.createBond()
                        // Maintain continuous interaction with a paired device.
                    }
                }
            }
            else -> super.onActivityResult(requestCode, resultCode, data)
        }
    }
}

جاوا

class MainActivityJava extends AppCompatActivity {

    private static final int SELECT_DEVICE_REQUEST_CODE = 0;
    Executor executor = new Executor() {
        @Override
        public void execute(Runnable runnable) {
            runnable.run();
        }
    };

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

        CompanionDeviceManager deviceManager =
            (CompanionDeviceManager) getSystemService(
                Context.COMPANION_DEVICE_SERVICE
            );

        // To skip filtering based on name and supported feature flags,
        // do not include calls to setNamePattern() and addServiceUuid(),
        // respectively. This example uses Bluetooth.
        BluetoothDeviceFilter deviceFilter =
            new BluetoothDeviceFilter.Builder()
                .setNamePattern(Pattern.compile("My device"))
                .addServiceUuid(
                    new ParcelUuid(new UUID(0x123abcL, -1L)), null
                )
                .build();

        // The argument provided in setSingleDevice() determines whether a single
        // device name or a list of device names is presented to the user as
        // pairing options.
        AssociationRequest pairingRequest = new AssociationRequest.Builder()
            .addDeviceFilter(deviceFilter)
            .setSingleDevice(true)
            .build();

        // When the app tries to pair with the Bluetooth device, show the
        // appropriate pairing request dialog to the user.
        deviceManager.associate(pairingRequest, new CompanionDeviceManager.Callback() {
            executor,
           // Called when a device is found. Launch the IntentSender so the user can
           // select the device they want to pair with.
           @Override
           public void onDeviceFound(IntentSender chooserLauncher) {
               try {
                   startIntentSenderForResult(
                       chooserLauncher, SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0
                   );
               } catch (IntentSender.SendIntentException e) {
                   Log.e("MainActivity", "Failed to send intent");
               }
           }

          @Override
          public void onAssociationCreated(AssociationInfo associationInfo) {
                 // AssociationInfo object is created and get association id and the
                 // macAddress.
                 int associationId = associationInfo.getId();
                 MacAddress macAddress = associationInfo.getDeviceMacAddress();
          }

          @Override
          public void onFailure(CharSequence errorMessage) {
             // Handle the failure.
        });
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        if (resultCode != Activity.RESULT_OK) {
            return;
        }
        if (requestCode == SELECT_DEVICE_REQUEST_CODE) {
            if (resultCode == Activity.RESULT_OK && data != null) {
                BluetoothDevice deviceToPair = data.getParcelableExtra(
                    CompanionDeviceManager.EXTRA_DEVICE
                );

                if (deviceToPair != null) {
                    deviceToPair.createBond();
                    // ... Continue interacting with the paired device.
                }
            }
        } else {
            super.onActivityResult(requestCode, resultCode, data);
        }
    }
}

در دستگاه‌هایی که Android 12L (سطح میانای برنامه‌سازی کاربردی ۳۲) یا پایین‌تر (منسوخ‌شده) را اجرا می‌کنند:

کاتلین

private const val SELECT_DEVICE_REQUEST_CODE = 0

class MainActivity : AppCompatActivity() {

    private val deviceManager: CompanionDeviceManager by lazy {
        getSystemService(Context.COMPANION_DEVICE_SERVICE) as CompanionDeviceManager
    }

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

        // To skip filters based on names and supported feature flags (UUIDs),
        // omit calls to setNamePattern() and addServiceUuid()
        // respectively, as shown in the following  Bluetooth example.
        val deviceFilter: BluetoothDeviceFilter = BluetoothDeviceFilter.Builder()
            .setNamePattern(Pattern.compile("My device"))
            .addServiceUuid(ParcelUuid(UUID(0x123abcL, -1L)), null)
            .build()

        // The argument provided in setSingleDevice() determines whether a single
        // device name or a list of them appears.
        val pairingRequest: AssociationRequest = AssociationRequest.Builder()
            .addDeviceFilter(deviceFilter)
            .setSingleDevice(true)
            .build()

        // When the app tries to pair with a Bluetooth device, show the
        // corresponding dialog box to the user.
        deviceManager.associate(pairingRequest,
            object : CompanionDeviceManager.Callback() {

                override fun onDeviceFound(chooserLauncher: IntentSender) {
                    startIntentSenderForResult(chooserLauncher,
                        SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0)
                }

                override fun onFailure(error: CharSequence?) {
                    // Handle the failure.
                }
            }, null)
    }

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        when (requestCode) {
            SELECT_DEVICE_REQUEST_CODE -> when(resultCode) {
                Activity.RESULT_OK -> {
                    // The user chose to pair the app with a Bluetooth device.
                    val deviceToPair: BluetoothDevice? =
                        data?.getParcelableExtra(CompanionDeviceManager.EXTRA_DEVICE)
                    deviceToPair?.let { device ->
                        device.createBond()
                        // Maintain continuous interaction with a paired device.
                    }
                }
            }
            else -> super.onActivityResult(requestCode, resultCode, data)
        }
    }
}

جاوا

class MainActivityJava extends AppCompatActivity {

    private static final int SELECT_DEVICE_REQUEST_CODE = 0;

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

        CompanionDeviceManager deviceManager =
            (CompanionDeviceManager) getSystemService(
                Context.COMPANION_DEVICE_SERVICE
            );

        // To skip filtering based on name and supported feature flags,
        // don't include calls to setNamePattern() and addServiceUuid(),
        // respectively. This example uses Bluetooth.
        BluetoothDeviceFilter deviceFilter =
            new BluetoothDeviceFilter.Builder()
                .setNamePattern(Pattern.compile("My device"))
                .addServiceUuid(
                    new ParcelUuid(new UUID(0x123abcL, -1L)), null
                )
                .build();

        // The argument provided in setSingleDevice() determines whether a single
        // device name or a list of device names is presented to the user as
        // pairing options.
        AssociationRequest pairingRequest = new AssociationRequest.Builder()
            .addDeviceFilter(deviceFilter)
            .setSingleDevice(true)
            .build();

        // When the app tries to pair with the Bluetooth device, show the
        // appropriate pairing request dialog to the user.
        deviceManager.associate(pairingRequest,
            new CompanionDeviceManager.Callback() {
                @Override
                public void onDeviceFound(IntentSender chooserLauncher) {
                    try {
                        startIntentSenderForResult(chooserLauncher,
                            SELECT_DEVICE_REQUEST_CODE, null, 0, 0, 0);
                    } catch (IntentSender.SendIntentException e) {
                        // failed to send the intent
                    }
                }

                @Override
                public void onFailure(CharSequence error) {
                    // handle failure to find the companion device
                }
            }, null);
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
        if (requestCode == SELECT_DEVICE_REQUEST_CODE) {
            if (resultCode == Activity.RESULT_OK && data != null) {
                BluetoothDevice deviceToPair = data.getParcelableExtra(
                    CompanionDeviceManager.EXTRA_DEVICE
                );

                if (deviceToPair != null) {
                    deviceToPair.createBond();
                    // ... Continue interacting with the paired device.
                }
            }
        } else {
            super.onActivityResult(requestCode, resultCode, data);
        }
    }
}

نمایه‌های دستگاه همپا

در Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۱) و بالاتر، برنامه‌های همراهی که دستگاه‌هایی مثل ساعت را مدیریت می‌کنند می‌توانند از نمایه‌های دستگاه همراه برای ساده‌سازی فرایند راه‌اندازی ازطریق اعطای اجازه‌های لازم هنگام جفت‌سازی استفاده کنند. برای اطلاعات بیشتر، به نمایه‌های دستگاه همپا مراجعه کنید.

بیدار نگه داشتن برنامه‌های همراه

از Android 16 (سطح API‏ ۳۶) به‌بعد،

CompanionDeviceManager.startObservingDevicePresence(String) و CompanionDeviceService.onDeviceAppeared() منسوخ شده‌اند.

باید از CompanionDeviceManager.startObservingDevicePresence (ObservingDevicePresenceRequest) برای مدیریت خودکار اتصال CompanionDeviceService پیاده‌سازی‌شده‌تان استفاده کنید.
- وضعیت اتصال CompanionDeviceService شما به‌طور خودکار براساس وضعیت حضور دستگاه همپای مرتبط با آن مدیریت می‌شود:
  1. وقتی دستگاه همپا در محدوده BLE باشد یا بااستفاده از بلوتوث متصل شده باشد، سرویس مقید می‌شود.
  2. وقتی دستگاه همپا از محدوده BLE خارج شود یا اتصال بلوتوث آن قطع شود، سرویس غیرمقید می‌شود.
برنامه براساس انواع DevicePresenceEvent، تماس برگشتی دریافت خواهد کرد.

برای جزئیات، به CompanionDeviceService.onDeviceEvent() مراجعه کنید.

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

پیاده‌سازی جفت‌سازی دستگاه همپا

مشخص کردن دستگاه‌های همپا

فهرست کردن دستگاه‌ها براساس DeviceFilter

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

نمایه‌های دستگاه همپا

بیدار نگه داشتن برنامه‌های همراه

جفت‌سازی دستگاه همپا

فهرست کردن دستگاه‌ها براساس `DeviceFilter`