TySS-Dev/nearby
1
0
Fork 0
mirror of https://github.com/kidfromjupiter/nearby.git synced 2026-09-16 07:36:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update Android README to expose more of the QS surfaces

Browse Source 
PiperOrigin-RevId: 623883363
This commit is contained in:
Anay Wadhera
2024-04-11 11:18:12 -07:00
committed by Copybara-Service
parent 10501ebf9c
commit 96374d7ba1
1 changed files with 92 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sharing/android/README.md
+92 -4
View File
@@ -1,12 +1,100 @@
# Nearby Sharing Android API
## The slice API
The nearby module in GMSCore provides a third-party accessible slice to bind to, to provide live data on nearby targets using Nearby Share. Clicking on any of these targets will take you to the main Nearby Share screen, where the transfer will begin and continually update the progress.
## Checking if Quick Share (Google) is supported on your device
Quick Share by Google has its own UI, and to use the below launch intents, the availability of these intents needs to be checked first.
This can be done by calling `PackageManager#queryIntentActivities()` with the intent required. A good rule of thumb to check if Quick Share is enabled is to run this check with the intent `com.google.android.gms.SHARE_NEARBY`.
Example code:
```kotlin
val shareIntent = Intent("com.google.android.gms.SHARE_NEARBY")
.setType("text/plain")
.putExtra(Intent.EXTRA_TEXT, "Hello Nearby");
val packageManager = context.packageManager;
val activities = packageManager.queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY);
// If the activities list is not empty, the intent can be handled and the intent can be called!
```
## Launching the settings page
The Google Quick Share settings page can be launched by sending an intent with the action `com.google.android.gms.settings.SHARING`. There are no extras to be provided.
Example code:
```kotlin
const val QUICK_SHARE_SETTINGS_INTENT = "com.google.android.gms.settings.SHARING"
context.startActivity(Intent(QUICK_SHARE_SETTINGS_INTENT))
```
## Launching the receiving UI
The Google Quick Share receiving UI can be launched by sending an intent with the action `com.google.android.gms.RECEIVE_NEARBY`. You will need to set the type of the intent to be `*/*` to match the filter.
Example code:
```kotlin
const val QUICK_SHARE_RECEIVE_INTENT = "com.google.android.gms.RECEIVE_NEARBY"
context.startActivity(Intent(QUICK_SHARE_RECEIVE_INTENT).setType("*/*"))
```
## Sending a file via Quick Share
Quick Share responds to the `android.intent.action.SEND` intent. To send a file, attach a content URI to the Intent.EXTRA_STREAM when sending the intent to send a file via Quick Share.
Example code:
```kotlin
val sendIntent = Intent(Intent.ACTION_SEND)
.setType(/* Set your content mime type here */)
.putExtra(Intent.EXTRA_STREAM, /* your content URI here */)
```
## Sending a folder via Quick Share
To send folders, Quick Share has a custom intent: `com.google.android.gms.nearby.SEND_FOLDER`.
### Mandatory extras
To place files in a parent folder, you can supply the following string extra: `com.google.android.gms.nearby.PARENT_FOLDER`. If this is not desirable, leave it as an empty string.
To provide the file count of the number of the files in the folder, supply the following extra: `com.google.android.gms.nearby.FILE_COUNT`. If this is not supplied, Quick Share will assume 0 files are in the folder.
To provide the actual content of the folder, supply the following extra: `com.google.android.gms.nearby.SEND_FOLDER_CONTENT_URI`. If not available, Quick Share will fail the transfer.
### Content provider
To share a folder, Quick Share expects the presence of a ContentProvider with the following columns:
* `file_name` - The name of the file.
* `file_uri` - The URI of the file, as given by a file provider.
* `file_size` - The size in bytes of the file.
* `file_dir` - The directory that the file should be placed in (parent directory under `/sdcard/Download/Quick Share`).
* `file_mime_type` - The mime type of the file.
Quick Share expects these columns to be populated for each file the user wants to share. The content URI provided is the URI to the content provider that can be queried for each file.
Putting this all together, we have the following intent structure:
```kotlin
val sendFolderIntent = Intent("com.google.android.gms.nearby.SEND_FOLDER")
.putExtra("com.google.android.gms.nearby.PARENT_FOLDER", /* The folder to save to under /sdcard/Download/Quick Share */)
.putExtra("com.google.android.gms.nearby.FILE_COUNT", /* The file count in the folder */)
.putExtra("com.google.android.gms.nearby.SEND_FOLDER_CONTENT_URI", /* Your content provider URI here */)
```
## Slice API
The nearby module in GMSCore provides a third-party accessible slice to bind to, to provide live data on nearby targets using Quick Share. Clicking on any of these targets will take you to the main Quick Share screen, where the transfer will begin and continually update the progress.
The slice URI is `content://com.google.android.gms.nearby.sharing/scan`. Upon first launch after install, you will be prompted to grant permission to the client application. After that, the slice will be kept up to date with the latest targets nearby.
## How to use the API ##
In Kotlin:
### How to use the API
Example code:
```kotlin
// Derive the Slice URI.
val sliceUri = Uri.parse("content://com.google.android.gms.nearby.sharing/scan")