Skip to content

Commit

Permalink
Adam/543 docs (#545)
Browse files Browse the repository at this point in the history 
* Update the usage-quickeditor.md docs

* Add docs for the migration to version 2.3
  • Loading branch information
@AdamGrzybkowski
AdamGrzybkowski authored Jan 23, 2025
1 parent e0d81b8 commit 88e0fa9
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 64 deletions.
90 changes: 26 additions & 64 deletions docs/get-started/usage-quickeditor.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,20 @@ To do that the QuickEditor needs an authorization token to perform requests on b

### 1. Let the Quick Editor handle the OAuth flow

#### 1.1 Using you own activity with `android:launchMode="singleTask"` (Recommended)

Quick Editor can handle the heavy lifting of running the full OAuth flow, so you don't have to do that. We will still need a few things from you.
First, you have to go to [OAuth docs](https://docs.gravatar.com/oauth/) and create your Application. Define the `Redirect URLs`.

> Keep in mind that you need to use the `https` scheme. Internally, QuickEditor uses Implicit OAuth flow (`response_type=token`) and for security reasons, the server doesn't allow custom URL schemes.
For the sake of this example let's assume the redirect URL is `https://yourhost.com/redirect-url`.

In your `AndroidManifest.xml` you need to add an `<intent-filter>` and the `android:launchMode="singleTask"` to the activity that will
launch the Quick Editor (or the last/main activity depending on your app architecture). This is important because the Quick Editor will be waiting for the `onNewIntent()` callback to handle OAuth redirection.
In your `AndroidManifest.xml` you need to setup `GravatarOAuthActivity` by adding the `<activity>` tag.
This Activity is launched by the Quick Editor when starting the OAuth flow and it handles the redirect URL to retrieve the token.

```xml
<activity
android:name=".YourActivity"
android:launchMode="singleTask"
...>
android:name="com.gravatar.quickeditor.ui.oauth.GravatarOAuthActivity"
tools:node="merge">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />

Expand Down Expand Up @@ -66,7 +63,7 @@ if (showBottomSheet) {
}
```

With the provided `clientId` and the `redirectUrl` Quick Editor can launch and handle the full OAuth flow. Once obtained the token will be stored in an encrypted Data Store.
With the provided `clientId` and the `redirectUrl` Quick Editor will launch and handle the full OAuth flow. Once obtained, the token will be stored in an encrypted Data Store.
This token will be later used in subsequent Quick Editor launches to make the user experience more seamless by not having to go through the OAuth flow each time.

When the user logs out form the app, make sure to run:
Expand All @@ -75,61 +72,6 @@ When the user logs out form the app, make sure to run:
GravatarQuickEditor.logout(Email("{USER_EMAIL}"))
```

#### 1.2 Using the provided activity

If using an activity with `android:launchMode="singleTask"` is not an option, you can use the provided activity. With this option, you don't need to modify how your activities are set up.

You need to add the provided activity to your `AndroidManifest.xml`:

```xml
<activity
android:name="com.gravatar.quickeditor.ui.GravatarQuickEditorActivity"
tools:node="merge">

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

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

<data
android:scheme="https"
android:host="yourhost.com"
android:pathPrefix="/redirect-url"
/>
</intent-filter>
</activity>
```

_Note the important difference here: the `tools:node="merge"` attribute. This is necessary to merge the intent filter with the one defined in the library._

The `GravatarQuickEditorActivity` defines an Activity Result contract that you can use to launch the Quick Editor and handle the result. Here's an example of how you can use it:

```kotlin
private val getQEResult = registerForActivityResult(GetQuickEditorResult()) { quickEditorResult ->
when (quickEditorResult) {
GravatarQuickEditorResult.AVATAR_SELECTED -> { ... }

GravatarQuickEditorResult.DISMISSED -> { ... }

else -> { ... }
}
}

getQEResult.launch(
GravatarQuickEditorActivity.GravatarEditorActivityArguments(
GravatarQuickEditorParams { ... },
AuthenticationMethod.OAuth(
OAuthParams { ... },
),
),
)
```

It's important to note that using the `GravatarQuickEditorActivity` you'll only receive the result of the Quick Editor when it's dismissed not instantly as with using the `@Composable` component from your `singleTask` activity (see [Section 1.1](#11-using-you-own-activity-with-androidlaunchmodesingletask-recommended)).

In the `demo-app` you can find a detailed implementation showing how to use the provided activity. See `QuickEditorTestActivity`.

#### Exclude Data Store files from Android backup (optional, but recommended)

Data Store files are subject to Android backups. Encrypted files from the backup won't work when restored on a different device so we have to exclude those files.
Expand Down Expand Up @@ -253,7 +195,7 @@ If you're using our UI Avatar component, you can simply enable the `forceRefresh
```kotlin
@Composable
public fun Avatar(
profile: Profile,
state: ComponentState<Profile>,
size: Dp,
modifier: Modifier = Modifier,
avatarQueryOptions: AvatarQueryOptions? = null,
Expand All @@ -263,6 +205,17 @@ public fun Avatar(

By setting `forceRefresh` to true, you ensure that the avatar is always fetched with the latest changes.

If you want a more fine-grained control with the `Avatar` component you can use the version that takes the URL as a parameter and pass the URL with the cacheBuster value created with the `AvatarUrl` class.

```kotlin
@Composable
public fun Avatar(
state: ComponentState<String>,
size: Dp,
modifier: Modifier = Modifier,
)
```

### Android Permissions

The Quick Editor module requires certain permissions to function correctly. Below is a table listing the permissions and the reasons why they are needed:
Expand All @@ -273,3 +226,12 @@ The Quick Editor module requires certain permissions to function correctly. Belo
| `WRITE_EXTERNAL_STORAGE` | Allows the app to save images to the device storage on Android 9 and lower via Download Manager. |

If you use the same permission with different configurations, you might end up with conflicts.

### Version migrations

When updating the SDK, you might need to migrate your code to the new version. Here is the list of all the migrations:

| Versions | Intructions |
|-------------------------|-------------------------------------------------|
| 2.x - 2.3.0 | [2.x-2.3.0](../version-migrations/2.x-2.3.0.md) |

57 changes: 57 additions & 0 deletions docs/version-migrations/2.x-2.3.0.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Migration from 2.x to 2.3.0

## GravatarOAuthActivity

In version 2.3.0, the `GravatarOAuthActivity` was introduced to handle OAuth authentication with Gravatar.
This means you no longer need to set up your Activity with the `launchMode=singleTask` to handle the `onNewIntent` method for OAuth redirection.

The Quick Editor will still work if you won't change it but it's highly recommended to migrate to the new `GravatarOAuthActivity` as this behavior will be removed in the future.

### Steps to Migrate

1. **Remove the extra config from you own Activity**:
If you have previously added this to you AndroidManifest.xml:

```xml
<activity
android:name=".YourActivity"
android:launchMode="singleTask"
...>
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />

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

<data
android:scheme="https"
android:host="yourhost.com"
android:pathPrefix="/redirect-url"
/>
</intent-filter>
</activity>
```

You can remove the `android:launchMode="singleTask"` and the `<intent-filter>` block.

2. **Add `GravatarOAuthActivity`**:
Ensure that the `GravatarOAuthActivity` is declared in your `AndroidManifest.xml`:

```xml
<activity
android:name="com.gravatar.quickeditor.ui.oauth.GravatarOAuthActivity"
tools:node="merge">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />

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

<data
android:scheme="https"
android:host="yourhost.com"
android:pathPrefix="/redirect-url"
/>
</intent-filter>
</activity>
```

0 comments on commit 88e0fa9

Please sign in to comment.