Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated README for Android #471

Merged
merged 3 commits into from
Oct 6, 2022
Merged

Updated README for Android #471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e415a43
ChangeLog.md -> CHANGELOG.md
handstandsam Oct 6, 2022
78fe035
Updated documentation around Android.
handstandsam Oct 6, 2022
4a7067c
Updated Documentation.
handstandsam Oct 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 ChangeLog.md → CHANGELOG.md
View file
Open in desktop
File renamed without changes.
76 changes: 56 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,35 +264,71 @@ To run individual tests, use the `--tests` gradle test filter:

## Usage on Android

Android support *** CALL OUT METHODS USED TO AUTHENTICATE ***
The Android code in this SDK is written in Kotlin (as of 5.4.x) and Kotlin is now a runtime dependency. If you do not already have Kotlin in your project, you will need to add `implementation("org.jetbrains.kotlin:kotlin-stdlib:1.6.21")` to your dependencies block in order to avoid a runtime exception.

### Required Dependencies For Android
The Android code in this SDK is written in Kotlin and is now a runtime dependency. If you do not already have Kotlin in your project, you will need to add `implementation("org.jetbrains.kotlin:kotlin-stdlib:1.6.21")` to your dependencies block.
At this point in time, the Android code is bundled with the main Java artifact, but will be published as a separate artifact at some point in the future.

The last published version without Kotlin is `5.3.0`. All future Android code will be written in Kotlin.
If the [official Dropbox App](https://play.google.com/store/apps/details?id=com.dropbox.android) is installed, it will attempt to use it to do authorization. If it is not, a web authentication flow is launched in-browser.

### `AndroidManifest.xml`
Use the methods in the [`Auth`](https://github.com/dropbox/dropbox-sdk-java/blob/main/dropbox-sdk-android/src/main/java/com/dropbox/core/android/Auth.kt) to start an authentication sessions.
* [`Auth.startOAuth2Authentication(...)`](https://github.com/dropbox/dropbox-sdk-java/blob/main/dropbox-sdk-android/src/main/java/com/dropbox/core/android/Auth.kt)
* [`Auth.startOAuth2PKCE(...)`](https://github.com/dropbox/dropbox-sdk-java/blob/main/dropbox-sdk-android/src/main/java/com/dropbox/core/android/Auth.kt)

The following two entries may need to be added to your `AndroidManifest.xml` depending on your target SDK level.
Please look at the `examples/android` sample app for usage as well.

For SDK levels >= `30`
```xml
<queries>
<package android:name="com.dropbox.android" />
</queries>
```
### Required Configuration for Authentication on Android

For SDK levels >= `33`
The following below is required configuration when using the SDK on Android.

See [#406](https://github.com/dropbox/dropbox-sdk-java/issues/406) for context
```xml
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
#### AndroidManifest.xml

Add these following pieces to your `AndroidManifest.xml` to use Dropbox for Authentication in Android.

##### Add `AuthActivity` to the manifest
Use your Dropbox APP Key in place of `dropboxKey` below. You need to add the `AuthActivity` entry, and it's associated `intent-filter`.
```
<manifest>
...
<application>
<activity
android:name="com.dropbox.core.android.AuthActivity"
android:exported="true"
android:configChanges="orientation|keyboard"
android:launchMode="singleTask">
<intent-filter>
<data android:scheme="db-${dropboxKey}" />

<action android:name="android.intent.action.VIEW" />

<category android:name="android.intent.category.BROWSABLE" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>

<!-- Additional intent-filter required as a workaround for Apps using targetSdk=33 until the fix in the Dropbox app is available to all users. -->
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
</application>
...
</manifest>
```

🚨[There is a known issue regarding apps with `targetSdk=33` regarding app-to-app authentication when the Dropbox App is installed](https://github.com/dropbox/dropbox-sdk-java/pull/471) 🚨
A fix is being worked on and will be released in an upcoming version of the Dropbox Mobile App.

We are working on pulling out this Android-specific code into its own android library with an `AndroidManifest.xml` that can be merged with your existing manifest, but in the meantime, this will work.
##### Add Dropbox `package` to `queries`
Additionally, you need to allow `queries` from the Dropbox official app for verification during the app-to-app authentication flow.
```
<manifest>
...
<queries>
<package android:name="com.dropbox.android" />
</queries>
...
</manifest>
```

## FAQ
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Run


Expand Down
2 changes: 1 addition & 1 deletion RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Please follow the steps in each one of the following sections to complete a rele
## Merge the Release to Trigger Publishing to Maven Central
1. Update the top level [gradle.properties](gradle.properties) to a non-SNAPSHOT version.
2. Update [DbxSdkVersion.java](DbxSdkVersion.java) to a non-SNAPSHOT version.
3. Update the [ChangeLog.md](ChangeLog.md) for the impending release.
3. Update the [CHANGELOG.md](CHANGELOG.md) for the impending release.
4. Update the [README.md](README.md) with the new version.
5. `git commit -am "Prepare for release X.Y.Z"` (where X.Y.Z is the new version)
6. Create a PR titled "Release vX.Y.Z"
Expand Down