Guide to Integrating the Workspace on Android
Introduction
This guide provides detailed instructions on how to integrate the GPTBots Workspace into an Android app, including permission requests, native and H5 interaction, and other related configurations.
GPTBots also provides a DEMO project for the Workspace to help you get started quickly. Android DEMO project: android-webview-bridge
Permission List
Basic Permissions
To ensure that Workspace-related features work properly, you need to configure the following permissions in AndroidManifest.xml:
<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 录音权限 -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<!-- 存储权限 -->
<!-- Android 13以下 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<!-- Android 13及以上 -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<!-- 其他辅助权限 -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
Permission Handling
To ensure the app can properly access sensitive permissions such as the microphone, camera, and photo gallery at runtime, the app should dynamically request the necessary runtime permissions on startup:
// Android 13及以上请求的权限
private final String[] permissionsForAndroid13 = {
Manifest.permission.RECORD_AUDIO,
Manifest.permission.READ_MEDIA_IMAGES,
Manifest.permission.READ_MEDIA_AUDIO,
Manifest.permission.READ_MEDIA_VIDEO
};
// Android 13以下请求的权限
private final String[] permissionsForBelowAndroid13 = {
Manifest.permission.RECORD_AUDIO,
Manifest.permission.READ_EXTERNAL_STORAGE,
Manifest.permission.WRITE_EXTERNAL_STORAGE
};
WebView Configuration
Basic Configuration
The app creates a WebView instance and applies the necessary settings:
WebSettings webSettings = webView.getSettings();
webSettings.setJavaScriptEnabled(true); // 启用 JavaScript
webSettings.setDomStorageEnabled(true); // 启用 DOM 存储 API
webSettings.setAllowFileAccess(true); // 允许访问文件
webSettings.setAllowContentAccess(true); // 允许访问内容 URL
webSettings.setMixedContentMode(WebSettings.MIXED_CONTENT_ALWAYS_ALLOW); // 允许混合内容
webSettings.setMediaPlaybackRequiresUserGesture(false); // 不需要用户手势即可播放媒体
Audio Recording Configuration
webSettings.setAllowFileAccessFromFileURLs(true); // 允许文件 URL 访问文件
webSettings.setAllowUniversalAccessFromFileURLs(true); // 允许通用访问
webSettings.setDatabaseEnabled(true); // 启用数据库
webSettings.setCacheMode(WebSettings.LOAD_DEFAULT); // 设置缓存模式
User-Agent Settings
String userAgent = webSettings.getUserAgentString();
webSettings.setUserAgentString(userAgent + " WebViewApp/1.0");
Workspace Access
Building the URL
Workspace access requires the Base URL and AiToken parameters:
String baseUrl = "https://gptbots.ai/space/h5/home";
String aiToken = "YOUR_AI_TOKEN"; // 替换为实际的AiToken
String fullUrl = baseUrl + "?AiToken=" + aiToken;
A default AiToken is preset in the app. If you need to change it, you can enter it on the login page.
For how to generate the AiToken, please refer to AiToken Encryption.
Loading the Page
webView.loadUrl(fullUrl);
WebView and Native Interaction
Registering the JavaScript Interface
webView.addJavascriptInterface(new JSBridge(), "agentWebBridge");
The H5 page calls native methods through the global object agentWebBridge.
Permission Handling
WebView Permission Requests
When the H5 page requests special permissions (such as audio recording), you need to handle the WebView's permission request:
webView.setWebChromeClient(new WebChromeClient() {
@Override
public void onPermissionRequest(PermissionRequest request) {
String[] requestedResources = request.getResources();
boolean hasAudioPermission = false;
for (String resource : requestedResources) {
if (PermissionRequest.RESOURCE_AUDIO_CAPTURE.equals(resource)) {
hasAudioPermission = true;
break;
}
}
if (hasAudioPermission) {
// 检查应用是否有录音权限
if (checkSelfPermission(Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED) {
request.grant(requestedResources);
} else {
// 请求系统权限
requestPermissions(new String[]{Manifest.permission.RECORD_AUDIO}, REQUEST_CODE);
// 存储权限请求,在获得权限后处理
pendingPermissionRequest = request;
}
} else {
// 其他权限直接授予
request.grant(requestedResources);
}
}
});
File Selection Handling
Handling file selection operations from the H5 page:
webView.setWebChromeClient(new WebChromeClient() {
@Override
public boolean onShowFileChooser(WebView webView, ValueCallback<Uri[]> filePathCallback, FileChooserParams fileChooserParams) {
// 保存回调
this.filePathCallback = filePathCallback;
// 创建文件选择 Intent
Intent intent = fileChooserParams.createIntent();
startActivityForResult(intent, REQUEST_FILE_CHOOSER);
return true;
}
});
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == REQUEST_FILE_CHOOSER) {
if (filePathCallback != null) {
Uri[] results = null;
if (resultCode == RESULT_OK && data != null) {
// 处理选择结果
// ...
}
filePathCallback.onReceiveValue(results);
filePathCallback = null;
}
}
}
Feature Examples
Closing the WebView
The H5 page can request to close the WebView as follows:
var message = {
eventType: "click",
data: {
value: "close"
}
};
agentWebBridge.callNative(JSON.stringify(message));
Native-side handling:
public void onClick(JSONObject data) {
String value = data.optString("value");
if (TextUtils.equals(value, "close")) {
closeWeb(data);
}
}
public void closeWeb(JSONObject data) {
// 通知 H5 即将关闭
JSONObject willCloseData = new JSONObject();
willCloseData.put("value", data.optString("value"));
willCloseData.put("reason", "user_request");
willCloseData.put("delay", 1000);
willCloseData.put("timestamp", System.currentTimeMillis());
webViewBridge.callH5(WebViewBridge.EVENT_CLICK, willCloseData);
// 延迟关闭 Activity
webView.postDelayed(() -> {
finish();
}, 1000);
}
