Skip to content

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 ​

java
/**
 * 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 ​

java
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;
}
FieldTypeDescription
countintMaximum number of images that can be selected
sizeTypeString[]Size type of the selected images, supports original, compressed
sourceTypeString[]Image source, supports album, camera

Parameter Values ​

sizeType ​

sizeType specifies the size type of the returned images.

ValueDescription
originalReturn the original image
compressedReturn the compressed image

Example:

java
params.sizeType = new String[]{"original"};

Or:

java
params.sizeType = new String[]{"compressed"};

If compressed is also included, the example implementation prioritizes processing as a compressed image:

java
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.

ValueDescription
albumSelect an image from the system album
cameraCapture an image with the camera

Example:

java
params.sourceType = new String[]{"album"};

Or:

java
params.sourceType = new String[]{"camera"};

Or:

java
params.sourceType = new String[]{"album", "camera"};

Return Value ​

Return the image selection result to the SDK via SUDOPStateHandle.

Selection Success ​

On selection success, call:

java
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:

json
{
  "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
    }
  ]
}
FieldTypeDescription
tempFilePathsString[]List of local temporary file paths generated after selecting images
tempFilesArrayList of image file information
tempFiles[].pathStringLocal temporary path of the image
tempFiles[].sizelongImage 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:

java
handle.failure(retCode, retMsg);
ParameterTypeDescription
retCodeintError code; 0 indicates success, non-0 indicates failure
retMsgStringError description

Example:

java
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 ​

java
@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 ​

java
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 ​

java
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 sizeType contains compressed, return the compressed image.

3. Determine the Image Source ​

java
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 ​

java
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");
}
ConditionBehavior
Supports both album and cameraCall showChooseDialog to let the user choose album or camera
Supports camera onlyCall selectCamera
Supports album onlyCall selectAlbum
Source cannot be identifiedCall handle.failure to return failure

text
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:

xml
<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 ScenarioSuggested Handling
sourceType is emptyReturn failure: sourceType fail to identify
sourceType does not contain album or cameraReturn failure
User cancels selectionReturn failure or cancellation status
User denies album permissionReturn failure and indicate permission denied
User denies camera permissionReturn failure and indicate permission denied
Camera unavailableReturn failure
Album picker fails to launchReturn failure
Image compression failsReturn failure
Temporary file generation failsReturn failure
Number of selected images exceeds countThe 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(...) or handle.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 when sizeType contains compressed.
  • Source validation: If sourceType does not contain album or camera, 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.