chooseImage
Choose Image
This method invokes the App-side image selection capability, letting the user choose an image from the system album or capture one with the camera, and returns the result to the SDK.
Common use cases include: uploading avatars, uploading images, choosing images to share, selecting in-game asset images, and uploading feedback screenshots.
Method Declaration
/**
* Choose image
*
* @param handle The state handle used to return the processing result to the SDK
* @param params Request parameters
*/
void chooseImage(SUDOPStateHandle handle, SUDOPChooseImageParams params);Parameters
SUDOPChooseImageParams
public class SUDOPChooseImageParams {
/**
* Maximum number of images that can be selected
*/
public int count;
/**
* Size of the selected images
* original: original image
* compressed: compressed image
*/
public String[] sizeType;
/**
* Source of the selected images
* album: select from the album
* camera: use the camera
*/
public String[] sourceType;
}| Field | Type | Description |
|---|---|---|
count | int | Maximum number of images that can be selected |
sizeType | String[] | Size type of the selected images, supports original, compressed |
sourceType | String[] | Image source, supports album, camera |
Parameter Values
sizeType
sizeType specifies the size type of the returned images.
| Value | Description |
|---|---|
original | Return the original image |
compressed | Return the compressed image |
Example:
params.sizeType = new String[]{"original"};Or:
params.sizeType = new String[]{"compressed"};If compressed is also included, the example implementation prioritizes processing as a compressed image:
boolean isOriginal = true;
if (sizeType != null) {
for (String type : sizeType) {
if ("compressed".equals(type)) {
isOriginal = false;
}
}
}sourceType
sourceType specifies the source of the selected images.
| Value | Description |
|---|---|
album | Select an image from the system album |
camera | Capture an image with the camera |
Example:
params.sourceType = new String[]{"album"};Or:
params.sourceType = new String[]{"camera"};Or:
params.sourceType = new String[]{"album", "camera"};Return Value
Return the image selection result to the SDK via SUDOPStateHandle.
Selection Success
On selection success, call:
handle.success(dataJson);The data returned on success is recommended to be a JSON string, usually containing the list of local temporary paths of the selected images.
Example:
{
"tempFilePaths": [
"/data/user/0/com.xxx.xxx/cache/image_1.jpg",
"/data/user/0/com.xxx.xxx/cache/image_2.jpg"
],
"tempFiles": [
{
"path": "/data/user/0/com.xxx.xxx/cache/image_1.jpg",
"size": 102400
},
{
"path": "/data/user/0/com.xxx.xxx/cache/image_2.jpg",
"size": 204800
}
]
}| Field | Type | Description |
|---|---|---|
tempFilePaths | String[] | List of local temporary file paths generated after selecting images |
tempFiles | Array | List of image file information |
tempFiles[].path | String | Local temporary path of the image |
tempFiles[].size | long | Image file size, in bytes |
The specific returned fields can be implemented according to the SDK's requirements. If the SDK has a fixed protocol for the return format, follow the SDK protocol.
Selection Failure
On selection failure or user cancellation, call:
handle.failure(retCode, retMsg);| Parameter | Type | Description |
|---|---|---|
retCode | int | Error code; 0 indicates success, non-0 indicates failure |
retMsg | String | Error description |
Example:
handle.failure(-1, "sourceType fail to identify");Runtime Behavior
- Triggered by the SDK: When the SDK needs the user to select or capture an image, it calls
chooseImage. - The App determines the image source: The App decides whether to use the album, camera, or a dialog for the user to choose, based on
params.sourceType. - The App determines the image quality: The App decides whether to return the original or compressed image, based on
params.sizeType. - The App invokes system capabilities: Depending on the source, it calls the system album picker or camera capture capability.
- Return local image paths: After the user selects or captures images, the App saves them as local temporary file paths and returns them via
handle.success(...). - Failure or cancellation callback: If the user cancels selection, permission is denied, image processing fails, etc., it needs to be returned via
handle.failure(...).
Example Code
@Override
public void chooseImage(SUDOPStateHandle handle, SUDOPChooseImageParams params) {
int count = params.count;
String[] sizeType = params.sizeType;
String[] sourceType = params.sourceType;
boolean isOriginal = true;
if (sizeType != null) {
for (String type : sizeType) {
if ("compressed".equals(type)) {
isOriginal = false;
}
}
}
boolean isAlbum = false;
boolean isCamera = false;
if (sourceType != null) {
for (String type : sourceType) {
if ("album".equals(type)) {
isAlbum = true;
} else if ("camera".equals(type)) {
isCamera = true;
}
}
}
if (isAlbum && isCamera) {
showChooseDialog(count, isOriginal, handle);
} else if (isCamera) {
selectCamera(count, isOriginal, handle);
} else if (isAlbum) {
selectAlbum(count, isOriginal, handle);
} else {
handle.failure(-1, "sourceType fail to identify");
}
}Example Implementation Logic
1. Get the Selection Count
int count = params.count;count indicates the maximum number of images that can be selected. The App side should limit the maximum number of images the user can select based on this value.
2. Determine the Image Size Type
boolean isOriginal = true;
if (sizeType != null) {
for (String type : sizeType) {
if ("compressed".equals(type)) {
isOriginal = false;
}
}
}In the example logic:
- By default, return the original image;
- If
sizeTypecontainscompressed, return the compressed image.
3. Determine the Image Source
boolean isAlbum = false;
boolean isCamera = false;
if (sourceType != null) {
for (String type : sourceType) {
if ("album".equals(type)) {
isAlbum = true;
} else if ("camera".equals(type)) {
isCamera = true;
}
}
}In the example logic:
- Contains
album: allow selecting from the album; - Contains
camera: allow capturing with the camera; - Contains both: pop up a selection dialog;
- Contains neither: return failure.
4. Execute the Corresponding Logic Based on the Source
if (isAlbum && isCamera) {
showChooseDialog(count, isOriginal, handle);
} else if (isCamera) {
selectCamera(count, isOriginal, handle);
} else if (isAlbum) {
selectAlbum(count, isOriginal, handle);
} else {
handle.failure(-1, "sourceType fail to identify");
}| Condition | Behavior |
|---|---|
| Supports both album and camera | Call showChooseDialog to let the user choose album or camera |
| Supports camera only | Call selectCamera |
| Supports album only | Call selectAlbum |
| Source cannot be identified | Call handle.failure to return failure |
Recommended Implementation Flow
SDK calls chooseImage
↓
App reads count, sizeType, sourceType
↓
Determine whether to return the original or compressed image
↓
Determine the image source: album / camera / both
↓
Check and request album or camera permissions
↓
Invoke the system album or camera
↓
User selects or captures an image
↓
Process the original or compressed image based on sizeType
↓
Generate the local temporary file path
↓
Selection success: handle.success(resultJson)
Selection failure/cancellation: handle.failure(retCode, retMsg)Permissions
Depending on the image source, the App side may need to handle the following permissions.
Album
Permissions may differ across Android versions:
- Android 13 and above: may require
READ_MEDIA_IMAGES - Android 12 and below: may require
READ_EXTERNAL_STORAGE - When using the system Photo Picker, storage permissions may not be required
Camera
Capturing an image with the camera usually requires:
<uses-permission android:name="android.permission.CAMERA" />If the photo is saved to an external directory, lower system versions may also require storage permissions.
Common Failure Scenarios
| Failure Scenario | Suggested Handling |
|---|---|
sourceType is empty | Return failure: sourceType fail to identify |
sourceType does not contain album or camera | Return failure |
| User cancels selection | Return failure or cancellation status |
| User denies album permission | Return failure and indicate permission denied |
| User denies camera permission | Return failure and indicate permission denied |
| Camera unavailable | Return failure |
| Album picker fails to launch | Return failure |
| Image compression fails | Return failure |
| Temporary file generation fails | Return failure |
Number of selected images exceeds count | The App should limit the selection count or truncate the result |
Notes
- Callback required: Whether the user's selection succeeds, fails, or is cancelled, you must call back the SDK via
handle.success(...)orhandle.failure(...). - count limit: The App side should limit the maximum number of images selected based on
params.count. - Default to original: The example implementation defaults to
isOriginal = true, and only returns the compressed image whensizeTypecontainscompressed. - Source validation: If
sourceTypedoes not containalbumorcamera, you need to return failure. - Permission requests: Before invoking the album or camera, you need to handle permissions according to the system version and implementation method.
- Temporary file paths: The image paths returned to the SDK are recommended to be local temporary file paths readable by the App.
- Network paths not applicable: This interface is used for locally selecting or capturing images, and should not directly return network image URLs.
- Invoke UI on the main thread: UI operations such as launching the album, camera, and dialogs should be executed on the main thread.
- Image compression is time-consuming: Operations such as image compression and copying to the temporary directory are recommended to be handled on a worker thread.
- Android version compatibility: It is recommended to prefer the system-recommended image selection approach and adapt to the permission policies of different Android versions.
