Skip to content

Commit 88e0fa9

Browse files
AdamGrzybkowskiAdamGrzybkowski
authored
Adam/543 docs (#545)
* Update the usage-quickeditor.md docs * Add docs for the migration to version 2.3
1 parent e0d81b8 commit 88e0fa9

2 files changed

Lines changed: 83 additions & 64 deletions

File tree

‎docs/get-started/usage-quickeditor.md‎

Lines changed: 26 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,20 @@ To do that the QuickEditor needs an authorization token to perform requests on b
66

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

9-
#### 1.1 Using you own activity with `android:launchMode="singleTask"` (Recommended)
10-
119
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.
1210
First, you have to go to [OAuth docs](https://docs.gravatar.com/oauth/) and create your Application. Define the `Redirect URLs`.
1311

1412
> 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.
1513
1614
For the sake of this example let's assume the redirect URL is `https://yourhost.com/redirect-url`.
1715

18-
In your `AndroidManifest.xml` you need to add an `<intent-filter>` and the `android:launchMode="singleTask"` to the activity that will
19-
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.
16+
In your `AndroidManifest.xml` you need to setup `GravatarOAuthActivity` by adding the `<activity>` tag.
17+
This Activity is launched by the Quick Editor when starting the OAuth flow and it handles the redirect URL to retrieve the token.
2018

2119
```xml
2220
<activity
23-
android:name=".YourActivity"
24-
android:launchMode="singleTask"
25-
...>
21+
android:name="com.gravatar.quickeditor.ui.oauth.GravatarOAuthActivity"
22+
tools:node="merge">
2623
<intent-filter android:autoVerify="true">
2724
<action android:name="android.intent.action.VIEW" />
2825

@@ -66,7 +63,7 @@ if (showBottomSheet) {
6663
}
6764
```
6865

69-
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.
66+
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.
7067
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.
7168

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

78-
#### 1.2 Using the provided activity
79-
80-
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.
81-
82-
You need to add the provided activity to your `AndroidManifest.xml`:
83-
84-
```xml
85-
<activity
86-
android:name="com.gravatar.quickeditor.ui.GravatarQuickEditorActivity"
87-
tools:node="merge">
88-
89-
<intent-filter>
90-
<action android:name="android.intent.action.VIEW" />
91-
92-
<category android:name="android.intent.category.DEFAULT" />
93-
<category android:name="android.intent.category.BROWSABLE" />
94-
95-
<data
96-
android:scheme="https"
97-
android:host="yourhost.com"
98-
android:pathPrefix="/redirect-url"
99-
/>
100-
</intent-filter>
101-
</activity>
102-
```
103-
104-
_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._
105-
106-
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:
107-
108-
```kotlin
109-
private val getQEResult = registerForActivityResult(GetQuickEditorResult()) { quickEditorResult ->
110-
when (quickEditorResult) {
111-
GravatarQuickEditorResult.AVATAR_SELECTED -> { ... }
112-
113-
GravatarQuickEditorResult.DISMISSED -> { ... }
114-
115-
else -> { ... }
116-
}
117-
}
118-
119-
getQEResult.launch(
120-
GravatarQuickEditorActivity.GravatarEditorActivityArguments(
121-
GravatarQuickEditorParams { ... },
122-
AuthenticationMethod.OAuth(
123-
OAuthParams { ... },
124-
),
125-
),
126-
)
127-
```
128-
129-
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)).
130-
131-
In the `demo-app` you can find a detailed implementation showing how to use the provided activity. See `QuickEditorTestActivity`.
132-
13375
#### Exclude Data Store files from Android backup (optional, but recommended)
13476

13577
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.
@@ -253,7 +195,7 @@ If you're using our UI Avatar component, you can simply enable the `forceRefresh
253195
```kotlin
254196
@Composable
255197
public fun Avatar(
256-
profile: Profile,
198+
state: ComponentState<Profile>,
257199
size: Dp,
258200
modifier: Modifier = Modifier,
259201
avatarQueryOptions: AvatarQueryOptions? = null,
@@ -263,6 +205,17 @@ public fun Avatar(
263205

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

208+
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.
209+
210+
```kotlin
211+
@Composable
212+
public fun Avatar(
213+
state: ComponentState<String>,
214+
size: Dp,
215+
modifier: Modifier = Modifier,
216+
)
217+
```
218+
266219
### Android Permissions
267220

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

275228
If you use the same permission with different configurations, you might end up with conflicts.
229+
230+
### Version migrations
231+
232+
When updating the SDK, you might need to migrate your code to the new version. Here is the list of all the migrations:
233+
234+
| Versions | Intructions |
235+
|-------------------------|-------------------------------------------------|
236+
| 2.x - 2.3.0 | [2.x-2.3.0](../version-migrations/2.x-2.3.0.md) |
237+

‎docs/version-migrations/2.x-2.3.0.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Migration from 2.x to 2.3.0
2+
3+
## GravatarOAuthActivity
4+
5+
In version 2.3.0, the `GravatarOAuthActivity` was introduced to handle OAuth authentication with Gravatar.
6+
This means you no longer need to set up your Activity with the `launchMode=singleTask` to handle the `onNewIntent` method for OAuth redirection.
7+
8+
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.
9+
10+
### Steps to Migrate
11+
12+
1. **Remove the extra config from you own Activity**:
13+
If you have previously added this to you AndroidManifest.xml:
14+
15+
```xml
16+
<activity
17+
android:name=".YourActivity"
18+
android:launchMode="singleTask"
19+
...>
20+
<intent-filter android:autoVerify="true">
21+
<action android:name="android.intent.action.VIEW" />
22+
23+
<category android:name="android.intent.category.DEFAULT" />
24+
<category android:name="android.intent.category.BROWSABLE" />
25+
26+
<data
27+
android:scheme="https"
28+
android:host="yourhost.com"
29+
android:pathPrefix="/redirect-url"
30+
/>
31+
</intent-filter>
32+
</activity>
33+
```
34+
35+
You can remove the `android:launchMode="singleTask"` and the `<intent-filter>` block.
36+
37+
2. **Add `GravatarOAuthActivity`**:
38+
Ensure that the `GravatarOAuthActivity` is declared in your `AndroidManifest.xml`:
39+
40+
```xml
41+
<activity
42+
android:name="com.gravatar.quickeditor.ui.oauth.GravatarOAuthActivity"
43+
tools:node="merge">
44+
<intent-filter android:autoVerify="true">
45+
<action android:name="android.intent.action.VIEW" />
46+
47+
<category android:name="android.intent.category.DEFAULT" />
48+
<category android:name="android.intent.category.BROWSABLE" />
49+
50+
<data
51+
android:scheme="https"
52+
android:host="yourhost.com"
53+
android:pathPrefix="/redirect-url"
54+
/>
55+
</intent-filter>
56+
</activity>
57+
```

0 commit comments

Comments
 (0)