این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

جفت شدن دستگاه همراه

در دستگاه‌های دارای Android 8.0 (سطح API 26) و بالاتر، جفت‌سازی دستگاه همراه، از طرف برنامه شما بدون نیاز به مجوز ACCESS_FINE_LOCATION ، دستگاه‌های اطراف را اسکن بلوتوث یا Wi-Fi انجام می‌دهد. این کمک می کند تا حفاظت از حریم خصوصی کاربر به حداکثر برسد. از این روش برای انجام پیکربندی اولیه دستگاه همراه، مانند ساعت هوشمند با قابلیت BLE استفاده کنید. علاوه بر این، جفت شدن دستگاه همراه نیاز به فعال کردن خدمات موقعیت مکانی دارد.

جفت شدن دستگاه همراه به خودی خود اتصال ایجاد نمی کند و اسکن مداوم را فعال نمی کند. برنامه‌ها می‌توانند از APIهای اتصال بلوتوث یا 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 ارائه می‌کنید مطابقت دارند (نشان داده شده در شکل 1) نمایش دهید. اگر می‌خواهید اسکن را فقط به یک دستگاه محدود کنید، می‌توانید setSingleDevice() روی true تنظیم کنید (نشان داده شده در شکل 2).

زیر کلاس های 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 می گیرد.

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

در دستگاه‌های دارای Android 13 (سطح API 33) و بالاتر:

کاتلین

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 (سطح API 32) یا پایین‌تر (منسوخ شده):

کاتلین

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 . وقتی کاربر یک دستگاه بلوتوث LE را انتخاب می کند، منتظر 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 (سطح API 33) و بالاتر:

کاتلین

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 (سطح API 32) یا پایین‌تر (منسوخ شده):

کاتلین

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 (سطح API 31) و بالاتر، برنامه‌های همراهی که دستگاه‌هایی مانند ساعت‌ها را مدیریت می‌کنند، می‌توانند از نمایه‌های دستگاه همراه برای ساده‌سازی فرآیند راه‌اندازی با دادن مجوزهای لازم هنگام جفت‌سازی استفاده کنند. برای اطلاعات بیشتر، به نمایه‌های دستگاه همراه مراجعه کنید.

برنامه های همراه را بیدار نگه دارید

در Android 12 (سطح API 31) و بالاتر، می‌توانید از APIهای اضافی برای کمک به اجرای برنامه همراهتان در زمانی که دستگاه همراه در محدوده است استفاده کنید. این API ها به شما امکان می دهند کارهای زیر را انجام دهید:

وقتی یک دستگاه همراه در محدوده است، برنامه خود را بیدار کنید.
برای جزئیات، CompanionDeviceManager.startObservingDevicePresence() را ببینید.
تضمین کنید که تا زمانی که دستگاه همراه در محدوده باقی بماند، یک فرآیند برنامه به اجرا ادامه خواهد داد.
برای جزئیات، CompanionDeviceService.onDeviceAppeared() را ببینید.

جفت شدن دستگاه همراه

پیاده سازی جفت شدن دستگاه همراه

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

لیست دستگاه ها بر اساس DeviceFilter

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

پروفایل های دستگاه همراه

برنامه های همراه را بیدار نگه دارید

لیست دستگاه ها بر اساس `DeviceFilter`