diff --git a/docs/native/debug/ios.md b/docs/native/debug/ios.md new file mode 100644 index 0000000000000000000000000000000000000000..0537b30d8792efca997c7f5b5e53b31f59263d4d --- /dev/null +++ b/docs/native/debug/ios.md @@ -0,0 +1,12 @@ +# 生成自定义基座 + +## 导出自定义基座 +1. 确保原生工程中`应用名称`、`versionName`、`versionCode`与离线资源中的`manifest.json`是否一致 +2. 确保`Target -> Info -> uniapp-x`节点下的`appid`与工程中`uni-app-x -> apps`下的目录名称以及该目录下`manifest.json`文件中的`id`三者是否一致 +3. 确保`Target -> Info -> uniapp-x`节点下的`uniRuntimeVersion`与`HBuilder X`版本号是否一致 +4. 在Xcode菜单栏中，选择`Product -> Archive` 根据提示导出ipa文件 + +## 导入HBuilderX +1. 将生成的`ipa`文件重命名为`iOS_debug.ipa` +2. 将`iOS_debug.ipa`拷贝到uni-app x项目的`unpackage/debug`目录下 +3. 点击 `运行 -> 运行到iOS App基座`，勾选`使用自定义基座运行` \ No newline at end of file diff --git a/docs/native/download/ios.md b/docs/native/download/ios.md new file mode 100644 index 0000000000000000000000000000000000000000..e5d633fe3dcd91d759d29e8124d095e877641943 --- /dev/null +++ b/docs/native/download/ios.md @@ -0,0 +1,3 @@ +# uni-app x iOS离线打包SDK + +## alpha版 diff --git a/docs/native/modules/ios/modules.md b/docs/native/modules/ios/modules.md new file mode 100644 index 0000000000000000000000000000000000000000..c648fbd970392096fbf3b2a7062cc2d9c8c18f9f --- /dev/null +++ b/docs/native/modules/ios/modules.md @@ -0,0 +1,363 @@ +## 集成/制作DCloudUTSExtAPI +> 参考demo中的DCloudUTSExtAPI工程 + +### 新建原生工程 +1. 启动`Xcode`，点击`File->New->Project`，选择`Framework`点击`Next` +2. `Product Name`中填写`DCloudUTSExtAPI`，`Language`选择为`Objective-C`，点击`Next`即可完成创建 + +> 你可以选择新建工程或直接使用demo中的`DCloudUTSExtAPI`工程 + +### 工程环境设置 +`Target -> General -> Minimum Deployments` 选择 `12.0` +`Target -> Build Settings -> Mach-O Type` 设置为`Dynamic Library` +`Target -> Build Settings -> Other Linker Flags` 中添加`-ObjC`, 字母o和c大写 +`Target -> Build Settings -> Enable Module Verifier` 设置为`NO` +`Target -> Build Settings -> Build Libraries for Distribution` 设置为`YES` +`Target -> Build Settings -> Framework Search Paths` 中添加SDK的Libs目录（操作方法：双击展开`Framework Search Paths`将`SDK/Libs`文件夹拖入即可） + +### 配置基础模块(必须) +将以下源文件(`SDK/ExtApiSrc 目录下`)、依赖库(`SDK/Libs 目录下`)添加到`DCloudUTSExtAPI`工程中，并将依赖库均设置为`Do Not Embed` + +| 源文件 | 依赖库 | 资源文件 | +| --- | ---| ---| +| UTSOC.h、UTSOC.mm、uni-getAppAuthorizeSetting-index.swift、uni-getAppBaseInfo-index.swift、uni-getDeviceInfo-index.swift、uni-getSystemInfo-index.swift、uni-getSystemSetting-index.swift、uni-openAppAuthorizeSetting-index.swift、uni-prompt-index.swift、uni-rpx2px-index.swift、uni-storage-index.swift、uni-theme-index.swift | DCloudUniappRuntime.xcframework、DCloudUTSFoundation.xcframework、DCUniToast.xcframework、DCloudAlertController.xcframework、storage.framework| uts-config.json | + +### 配置其他模块(可选) +根据离线资源中的`manifest.json`文件包含的模块名称，选择以下源文件(`SDK/ExtApiSrc 目录下`)、依赖库(`SDK/Libs 目录下`)添加到DCloudUTSExtAPI工程中，依赖库均设置为`Do Not Embed` +| 模块名称 | 源文件 | 依赖库 | 系统依赖库 | +|---|---|---|---| +| uni-createWebviewContext | uni-createWebviewContext-index.swift | | | +| uni-getProvider | uni-getProvider-index.swift | | | +| uni-network | uni-network-index.swift | | | +| uni-getNetworkType | uni-getNetworkType-index.swift | | | +| uni-websocket | uni-websocket-index.swift | websocket.xcframework、Starscream.xcframework | | +| uni-media | uni-media-index.swift | DCloudMediaPicker.xcframework | AssetsLibrary、Photos、AVFoundation、CoreServices、CoreFoundation、CoreGraphics、CoreImage、GLKit、MetalKit、MobileCoreServices、QuartzCore、ImageIO、MediaPlayer、CoreText | +| uni-payment-alipay | uni-payment-alipay-index.swift、uni-payment-index.swift | AlipaySDK.xcframework |c++、z、SystemConfiguration、CoreTelephony、QuartzCore、CoreText、CoreGraphics、CFNetwork、CoreMotion | +| uni-payment-wxpay | uni-payment-wxpay-index.swift、uni-payment-index.swift | libWeChatSDK.a | CoreGraphics、WebKit、Security | +| uni-getLocation-system | uni-getLocation-system-index.swift | | | +| uni-video | uni-video-index.swift | DCUniVideo.xcframework、IJKMediaFrameworkWithSSL.xcframework、UniDCSVProgressHUD.xcframework | | +| uni-push | uni-push-index.swift | GTCommonSDK.xcframework、GTSDK.xcframework、ZXSDK.framework | c++、resolv、z、sqlite3、MobileCoreServices、Security、SystemConfiguration、CoreTelephony、AVFoundation、UserNotifications、AdSupport | +| uni-verify | uni-verify-index.swift、uni-network-index.swift | GTCommonSDK.xcframework、GeYanSdk.xcframework | resolv.9、c++、z、sqlite3.0、WebKit、CoreFoundation、Network、AdSupport | +| uni-ad | uni-ad-index.swift | DCUniAdFoundation.xcframework | | +| uni-facialRecognitionVerify | uni-facialRecognitionVerify-index.swift | AliyunFaceAuthFacade.framework、AliyunMobileRPC.framework、AliyunOSSiOS.framework、APBToygerFacade.framework、APPSecuritySDK.framework、BioAuthAPI.framework、BioAuthEngine.framework、deviceiOS.framework、DTFIdentityManager.framework、DTFSensorServices.framework、DTFUIModule.framework、DTFUtility.framework、MPRemoteLogging.framework、ToygerNative.framework、ToygerService.framework | c++、z、resolv、c++.1、c++abi、z.1.2.8、Accelerate、AssetsLibrary、QuartzCore、CoreFoundation、CoreLocation、ImageIO、CoreMedia、CoreMotion、AVFoundation、WebKit、AudioToolbox、CFNetwork、MobileCoreServices、SystemConfiguration、CoreTelephony、QuartzCore、CoreGraphics、AdSupport | + + +### 配置uts-config.json(可选) + +在`DCloudUTSExtAPI`工程中新建 `uts-config.json` 文件， +uni-video模块需要添加如下配置 +``` +{ + "components": [{ + "name": "video", + "class": "UTSSDKModulesDCloudUniVideoVideoComponent", + "delegateClass": "VideoComponentRegister" + }] +} +``` +uni-payment-alipay模块需要添加如下配置 +``` +{ + "hooksClasses": [ + "UTSSDKModulesDCloudUniPaymentAlipayAlipayHookProxy" + ], + "providers": [{ + "name": "alipay", + "service": "payment", + "class": "UTSSDKModulesDCloudUniPaymentAlipayUniPaymentAlipayProvider" + }] +} +``` +uni-payment-wxpay模块需要添加如下配置 +``` +{ + "hooksClasses": [ + "UTSSDKModulesDCloudUniPaymentWxpayWxpayHookProxy" + ], + "providers": [{ + "name": "wxpay", + "service": "payment", + "class": "UTSSDKModulesDCloudUniPaymentWxpayUniPaymentWxpayProvider" + }] +} +``` +`uts-config.json`配置示例图 +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/utsconfig.png) + + +### 编译导出DCloudUTSExtAPI.xcframework +选择构建目标(Any iOS Device/Any iOS Simulator Device)，在菜单栏中，选择`Product -> Build`（或使用快捷键`Command + B`），分别编译出真机以及模拟器的Framework文件。 +在菜单栏中，选择`Product -> Copy Build Floder Path` 获取编译产物所在路径。 +使用xcodebuild命令行创建xcframework +``` +xcodebuild -create-xcframework -framework 真机路径/DCloudUTSExtAPI.framework -framework 模拟器路径/DCloudUTSExtAPI.framework -output 导出路径/DCloudUTSExtAPI.xcframework +``` +导出成功后，将 `DCloudUTSExtAPI.xcframework` 添加到主工程，并设置为 `Embed && Sign` + +**> 编译模拟器注意事项 +> `Apple芯片`的设备编译模拟器需要在菜单栏中点击 `Product -> Destination -> Show All Run Destinations` ，然后选择 `Rosetta模拟器` 编译** + + + +## 主工程配置 +根据离线资源中的`manifest.json`文件包含的模块名称，根据下述相关模块文档向`主工程`添加依赖以及工程配置 +## uni-prompt +### 添加依赖库以及资源文件 +| 资源文件 | +|---| +| uni_uts_toast_error.png、uni_uts_toast_success.png | +## uni-media +### 添加依赖库以及资源文件 +| 依赖库 | 资源文件 | +|---|---| +| DCloudPermissionAlbum.xcframework、DCloudPermissionCamera.xcframework、DCloudPermissionMicrophone.xcframework | DCMediaEditingController.bundle、DCTZImagePickerController.bundle | + +### Info.plist +添加`相机权限描述(NSCameraUsageDescription)`、`麦克风权限描述(NSMicrophoneUsageDescription)`、`相册读写权限描述(NSPhotoLibraryUsageDescription)`、`相册写权限描述(NSPhotoLibraryAddUsageDescription)` +``` + + NSCameraUsageDescription + 需要您的同意，才能使用摄像头，以便于相机拍摄 + NSMicrophoneUsageDescription + 需要您的同意，才能使用麦克风，以便于录制音频 + NSPhotoLibraryUsageDescription + 需要您的同意，才能访问相册，以便于图像选取 + NSPhotoLibraryAddUsageDescription + 需要您的同意，才能访问相册，以便于保存图像 + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/unimedia_permission.png) + +## uni-getLocation-system +### 添加依赖库以及资源文件 +| 依赖库 | +|---| +| DCloudPermissionLocation.xcframework | + +### Info.plist +添加`仅运行期间使用定位权限描述(NSLocationWhenInUseUsageDescription)`、`始终使用定位权限描述(NSLocationAlwaysAndWhenInUseUsageDescription)`、`使用临时位置权限描述(NSLocationTemporaryUsageDescriptionDictionary)` + +``` + + NSLocationAlwaysAndWhenInUseUsageDescription + 需要您的同意，才能访问位置信息 + NSLocationWhenInUseUsageDescription + 需要您的同意，才能在仅运行期间获取位置信息 + NSLocationTemporaryUsageDescriptionDictionary + + YourPurposeKey + 这里需要您临时授权高精度定位权限,一次临时授权时效仅app一个周期内, 每次硬启动都需要临时授权 + + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/location_permission.png) + + +## uni-payment-alipay + +### 添加依赖库以及资源文件 +| 资源文件 | +|---| +| AlipaySDK.bundle | + +### Info.plist +1. 添加 `白名单(LSApplicationQueriesSchemes)` + ``` + LSApplicationQueriesSchemes + + safepay + alipay + + ``` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/alipay_queriesSchemes.png) + +2. 添加 `URLSchemes(CFBundleURLTypes)`，`$appid_md5`建议使用`alipay`的`appid`的md5值 + ``` + CFBundleURLTypes + + + CFBundleTypeRole + Editor + CFBundleURLName + Alipay + CFBundleURLSchemes + + alipay$appid_md5 + + + + ``` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/alipay_urlTypes.png) + +3. 添加 `Alipay` 配置项 + ``` + Alipay + + universalLink + 此处填写通用链接 + + ``` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/alipay_info.png) + + +### Capability +`Target -> Signing & Capabilities` 点击 左上角`+ Capability `添加`Associated Domains`，将配置了 `Universal Links` 的域名加到 Domains 配置中 +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/associated_domains.png) + + +## uni-payment-wxpay + +### Info.plist +1. 添加 `白名单(LSApplicationQueriesSchemes)` + ``` + LSApplicationQueriesSchemes + + weixin + weixinULAPI + weixinURLParamsAPI + + ``` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/wechat_queriesSchemes.png) + +2. 添加 `URLSchemes(CFBundleURLTypes)` + ``` + CFBundleURLTypes + + + CFBundleTypeRole + Editor + CFBundleURLName + WeChat + CFBundleURLSchemes + + 微信的appid + + + + ``` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/wechat_urltypes.png) + +3. 添加 `WeChat` 配置项 + ``` + WeChat + + appid + 此处填写微信的appid + universalLink + 此处填写微信开放平台注册的通用链接 + + ``` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/wechat_info.png) + +### Capability +`Target -> Signing & Capabilities` 点击 左上角`+ Capability `添加`Associated Domains`，将配置了 `Universal Links` 的域名加到 Domains 配置中 +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/associated_domains.png) + + +## uni-push + +### 添加依赖库以及资源文件 +| 依赖库 | +|---| +| DCloudPermissionPush.xcframework | + +### Info.plist +1. 添加`通知权限描述(NSUserNotificationsUsageDescription)` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/unipush_permission.png) + +2. 添加 `getui` 配置项 +``` + getui + + appid + 此处填写getui的appid + appKey + 此处填写getui的appKey + appSecret + 此处填写getui的appSecret + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/unipush_info.png) + + +### Capability +`Target -> Signing & Capabilities` 点击 左上角`+ Capability `， +分别添加`Access Wi-Fi Information`、`Push Notifications`、`Time Sensitive Notifications` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/unipush_capability.png) + + +## uni-verify + +### Info.plist +1. 添加 `geyan` 配置项 +``` + geyan + + appid + 此处填写geyan的appid + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/geyan_info.png) + + +## uni-facialRecognitionVerify +### 添加依赖库以及资源文件 +| 依赖库 | 资源文件 | +|---|---| +| DCloudPermissionCamera.xcframework | APBToygerFacade.bundle、BioAuthEngine.bundle、ToygerNative.bundle | + +### Info.plist +添加`相机权限描述(NSCameraUsageDescription)` +``` + + NSCameraUsageDescription + 需要您的同意，才能使用摄像头，以便于相机拍摄 + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/camera_permission.png) + + +## uni-ad +### 基础广告(必须) +#### 添加依赖库以及资源文件 +| 依赖库 | 资源文件 | +|---|---| +| DCUniAdFoundation.xcframework`（Embed & Sign）` | DCUniAdSDK.bundle | + +#### Info.plist +进入[uni-ad后台](https://uniad.dcloud.net.cn/)，复制首页中的联盟ID,将其添加到`uniapp-x` 节点下的 `unionid` 字段中 + +``` +uniapp-x + + unionid + 广告联盟id，如未开通uniad可不填 + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/uniappx_info.png) + +### 增强广告(可选) +#### 添加依赖库以及资源文件 +| 广告渠道 | 依赖库 | 资源文件 | 系统库 | +|---|---|---|---| +| 优量汇 | DCUniAdGdt.xcframework、libGDTMobSDK.a、DCloudPermissionIDFA.xcframework | | AppTrackingTransparency、AdSupport、CoreLocation、QuartzCore、SystemConfiguration、CoreTelephony、Security、StoreKit、AVFoundation、WebKit、JavaScriptCore、z、xml2、sqlite3、c++ | +| Gromore | DCUniAdGm.xcframework、CSJMediation.xcframework、BUAdSDK.xcframework、DCloudPermissionIDFA.xcframework | CSJAdSDK.bundle | AppTrackingTransparency、Accelerate、AdSupport、AudioToolbox、AVFoundation、CoreGraphics、CoreImage、CoreLocation、CoreMotion、CoreMedia、CoreTelephony、CoreText、ImageIO、JavaScriptCore、MapKit、MediaPlayer、MobileCoreServices、QuartzCore、SystemConfiguration、Security、StoreKit、WebKit、DeviceCheck、z、xml2、sqlite3、c++、bz2、iconv、resolv.9、c++abi | +| 快手 | DCUniAdKs.xcframework、DCloudPermissionIDFA.xcframework、KSAdSDK.xcframework`（Embed & Sign）` | | AppTrackingTransparency、AdSupport、MobileCoreServices、CoreGraphics、CoreData、CoreLocation、MediaPlayer、CoreMedia、WebKit、Accelerate、AVKit、MessageUI、QuickLook、AddressBook、CoreMotion、QuartzCore、SystemConfiguration、CoreTelephony、Security、StoreKit、AVFoundation、WebKit、z、resolv.9、sqlite3、c++、c++abi | +| 百度 | DCUniAdBd.xcframework、DCloudPermissionIDFA.xcframework、BaiduMobAdSDK.framework | baidumobadsdk.bundle | AppTrackingTransparency、AdSupport、StoreKit、SafariServices、MessageUI、CoreMedia、CoreMotion、SystemConfiguration、CoreLocation、CoreTelephony、AVFoundation、Webkit、c++ | +| sigmob | DCUniAdSgm.xcframework、DCloudPermissionIDFA.xcframework、WindSDK.xcframework、WindFoundation.xcframework | | AppTrackingTransparency、AdSupport、StoreKit、CFNetwork、CoreMedia、CoreGraphics、AVFoundation、CoreLocation、CoreTelephony、SafariServices、MobileCoreServices、WebKit、SystemConfiguration、ImageIO、z、sqlite3 | + + +#### Info.plist +添加`IDFA权限描述(NSUserTrackingUsageDescription)` +``` + + NSUserTrackingUsageDescription + 获取标记权限向您提供更优质、安全的个性化服务及内容，未经同意我们不会用于其他目的；开启后，您也可以前往系统“设置-隐私 ”中随时关闭 + +``` +开通 `快手、sigmob、百度` 渠道建议添加以下权限描述 +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/location_permission.png) + + +#### 隐私清单 +开通 `优量汇、Gromore` 渠道需要将该渠道的隐私清单内容手动合并到主工程的隐私清单文件中，详见目录`SDK/PrivacyInfo/优量汇`，`SDK/PrivacyInfo/Gromore` \ No newline at end of file diff --git a/docs/native/use/ios.md b/docs/native/use/ios.md new file mode 100644 index 0000000000000000000000000000000000000000..00a9ea84f575ea2e5a27c82bcea0b55a878299e6 --- /dev/null +++ b/docs/native/use/ios.md @@ -0,0 +1,87 @@ +# uni-app x 原生SDK iOS版 + +## 准备环境 +* HBuilder X (4.23及以上版本） +* Xcode 15.2及以上版本 + +## 接入流程 +* 通过 `HBuilder X` 导出离线资源，根据资源内容，配置**原生主工程**环境，添加基础模块需要的依赖库以及资源文件 +* 根据离线资源中的`manifest.json`文件中包含的模块，制作`DCloudUTSExtAPI.xcframework`，并将其添加到**原生主工程**中，详见[集成内置模块](../modules/ios/modules.md) +* 根据离线资源中的`manifest.json`文件中包含的模块，向**原生主工程**添加工程配置以及内置模块需要的资源文件等，详见[集成内置模块](../modules/ios/modules.md) +* 根据离线资源中的`uni_modules`文件夹中包含的UTS插件，制作对应的原生xcframework，并将其添加到**原生主工程**(付费购买的uts插件不支持离线打包)，详见[制作UTS插件](iosuts.md) +* 编写代码通过离线API初始化SDK，详见[接入API](iosapi.md) + +## 新建项目(已有可跳过) +1. 启动`Xcode`，点击`File->New->Project`，选择`App`点击`Next` +2. 填写`Product Name`，`Language`选择为`Swift`，点击`Next`即可完成创建 + +## 主工程环境配置 +`Target -> General -> Minimum Deployments` 选择 `12.0` +`Target -> Build Settings -> Other Linker Flags` 中添加`-ObjC`、`-ld_classic`、`-weak_framework SwiftUI` +`Target -> General -> Identity -> Display Name` 输入应用名称(`manifest.json`文件中的`name`) +`Target -> General -> Identity -> Bundle Identifier` 输入应用标识 +`Target -> General -> Identity -> Version` 输入应用`versionName` +`Target -> General -> Identity -> Build` 输入应用`versionCode` + +## Info.plist配置 + +`Target -> Info` 下，添加如下配置 +``` + + NSAppTransportSecurity + + NSAllowsArbitraryLoads + + + uniapp-x + + appid + 您应用的appid + ipatype + 1 + singleThread + + uniRuntimeVersion + 离线SDK版本号 + unionid + 广告联盟id，如未开通uniad可不填 + + +``` +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/uniappx_info.png) + + +## 导出离线资源 +1. 在主工程中新建文件目录`uni-app-x/apps` + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/create_resources_document.png) + +2. 打开 `HBuilder X -> 发行 -> 原生App-本地打包 -> 生成本地打包App资源` 勾选iOS 点击生成 + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/export.png) + + +3. 导出成功之后会在项目的`unpackage/resources`目录下生成资源文件 + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/resources.png) + +4. 将 `app-ios` 目录下与`appid`对应的目录拷贝到主工程的 `uni-app-x/apps` 目录下 + ![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/copy_resources.png) + + +## 集成基础模块 +将以下依赖库(`SDK/Libs 目录下`)添加到工程中 + +| 依赖库 | 系统依赖库 | +| --- | ---| +| DCloudDebugServe.xcframework `（Do Not Embed）Debug环境下集成`、DCloudUTSFoundation.xcframework `（Embed & Sign）`、DCloudUniappRuntime.xcframework `（Embed & Sign）`、SDWebImage.xcframework `（Embed & Sign）`、DCloudUTSExtAPI.xcframework `（Embed & Sign）` | JavaScriptCore.framework、c++ | + +> `Target -> Build Phases -> Link Binary With Libraries` 下添加依赖库 +> `Target -> General -> Frameworks,Libraries,and Embedded Content` 下设置`Embed & Sign` +> DCloudUTSExtAPI.xcframework如何获取详见[集成内置模块](../modules/ios/modules.md) + +## 集成内置模块 +根据[集成内置模块](../modules/ios/modules.md)制作`DCloudUTSExtAPI`以及向主工程添加相关配置 + +## 集成UTS插件 +根据[集成UTS插件](iosuts.md)制作插件库以及向主工程添加相关配置 + +## 接入离线SDK +根据[接入离线SDK](iosapi.md)在`主工程`编写代码完成接入 \ No newline at end of file diff --git a/docs/native/use/iosapi.md b/docs/native/use/iosapi.md new file mode 100644 index 0000000000000000000000000000000000000000..7150b50948f87bee9dd8c8b82b4d92e1f5a6b87c --- /dev/null +++ b/docs/native/use/iosapi.md @@ -0,0 +1,73 @@ +> * 仅需要离线打包可直接使用或参考`HBuilder`工程 +> * 原生项目接入离线SDK可参考示例`UniAppXDemo`工程 +> * 离线SDK基于Swift开发，因此原生Objective-C语言开发的应用需要新建一个Swift文件用于添加Swift运行环境以及桥接离线SDK的API，详情可参考UniAppXDemo工程中的`UniAppBridge` + +# 仅离线打包 +参考如下示例修改AppDelegate(建议直接使用示例中的`HBuilder`工程) +``` +import DCloudUniappRuntime +@main +class AppDelegate: UniAppRootAppDelegate { +} +``` +# 采用SDK方式接入 + +## 初始化SDK +在 AppDelegate 的 didFinishLaunchingWithOptions 中初始化 +``` +import DCloudUniappRuntime + +UniSDKEngine.shared.create() +``` +## 监听应用生命周期函数回调 +在 AppDelegate 的 didFinishLaunchingWithOptions调用 +``` +UniSDKEngine.applicationDidFinishLaunchingWithOptions(application, launchOptions) +``` +在 AppDelegate 的 applicationDidBecomeActive 调用 +``` +UniSDKEngine.applicationDidBecomeActive(application) +``` +在 AppDelegate 的 applicationWillResignActive 调用 +``` +UniSDKEngine.applicationWillResignActive(application) +``` +在 AppDelegate 的 applicationDidEnterBackground 调用 +``` +UniSDKEngine.applicationDidEnterBackground(application) +``` +在 AppDelegate 的 applicationWillEnterForeground 调用 +``` +UniSDKEngine.applicationWillEnterForeground(application) +``` +在 AppDelegate 的 openURL 调用 +``` +UniSDKEngine.applicationOpenURLOptions(application, url, options) +``` +在 AppDelegate 的 continueUserActivity 调用 +``` +UniSDKEngine.applicationContinueUserActivityRestorationHandler(application, userActivity, restorationHandler) +``` + +## 监听推送相关函数回调(可选) +在 AppDelegate 的 didRegisterForRemoteNotificationsWithDeviceToken 调用 +``` +UniSDKEngine.didRegisterForRemoteNotifications(deviceToken) +``` +在 AppDelegate 的 didFailToRegisterForRemoteNotificationsWithError 调用 +``` +UniSDKEngine.didFailToRegisterForRemoteNotifications(error) +``` +在 AppDelegate 的 didReceiveRemoteNotification 调用 +``` +UniSDKEngine.applicationDidReceiveRemoteNotificationCompletionHandler(application, userInfo, completionHandler) +``` + +## 开始渲染 +``` +UniSDKEngine.shared.render(toView: toView) +``` + + +# 通信 +iOS平台目前不支持直接在uvue页面调用原生API，开发者可通过UTS插件`发送or接收Notification`实现与原生通信 diff --git a/docs/native/use/iosuts.md b/docs/native/use/iosuts.md new file mode 100644 index 0000000000000000000000000000000000000000..348d67bfe5906071a7343728545c7d03dadd6eb9 --- /dev/null +++ b/docs/native/use/iosuts.md @@ -0,0 +1,66 @@ +# 制作UTS插件 +> 1. 付费uts插件不支持离线打包。 +> 2. 如果导出的离线资源不包含 `uni_modules` ，或 `uni_modules` 中的插件均不包含 `app-ios` 目录可以跳过此章节 + +## 新建原生插件工程 +根据离线资源下的`uni_modules`下的插件列表，新建原生插件工程 +1. 启动`Xcode`，点击`File->New->Project`，选择`Framework`点击`Next`； +2. `Product Name`填写规则为：`unimodule`+`插件名称`，其中`-`分割改为驼峰，比如`uni-getbatteryinfo`插件对应的原生工程名应为`unimoduleUniGetbatteryinfo` +3. `Language`选择为`Objective-C`，点击`Next`即可完成创建 + +## 插件工程环境配置 + `Target -> General -> Minimum Deployments` 选择 `12.0` + `Target -> Build Settings -> Mach-O Type` 设置为`Dynamic Library` + `Target -> Build Settings -> Other Linker Flags` 中添加`-ObjC`, 字母o和c大写 + `Target -> Build Settings -> Build Libraries for Distribution` 设置为`YES` + `Target -> Build Settings -> Framework Search Paths` 中添加SDK的Libs目录（操作方法：双击展开`Framework Search Paths`将`SDK/Libs`文件夹拖入即可） + +`插件工程`中新建`uts-config.json`文件，然后将离线SDK中`SDK/ExtApiSrc/UTSOC.h`以及`SDK/ExtApiSrc/UTSOC.mm`添加到`插件工程`中 + +## 添加基础依赖 +将以下源文件(`SDK/ExtApiSrc 目录下`)、依赖库(`SDK/Libs 目录下`)添加到`插件工程`中，并将依赖库均设置为`Do Not Embed` +| 源文件 | 依赖库 | 资源文件 | +|---|---|---| +| UTSOC.h、UTSOC.mm | DCloudUniappRuntime.xcframework、DCloudUTSExtAPI.xcframework、DCloudUTSFoundation.xcframework| uts-config.json | + +> DCloudUTSExtAPI.xcframework的制作详见[集成内置模块](../modules/ios/modules.md) + +## 配置离线资源 +将导出的离线资源中`uni_modules`目录下的插件资源，按以下列表中的配置方式分别在`主工程`和`插件工程`添加依赖资源 +| 目录名/文件名 | 用途 | 配置 | +|---|---|---| +| Frameworks | 插件依赖的三方库(framework/xcframework) | 将目录下的依赖库添加到`插件工程`中 | +| Libs | 插件依赖的三方库(.a) | 将目录下的依赖库添加到`插件工程`中 | +| src | 插件源代码 | 将目录下的源代码添加到`插件工程`中 | +| Resources | 插件需要引用的资源文件存放目录 | 将目录下的资源文件添加到`主工程`中 | +| Info.plist | 需要添加到原生主工程`Info.plist`中的配置文件 | 将该文件配置添加到`主工程`的`Info.plist`中，注意去重 | +| UTS.entitlements | 需要添加到原生主工程 `entitlements` 文件中的配置文件 | 根据该文件内容，在主工程中添加对应的`Capability` | +| config.json | 插件依赖的`系统库`、`cocoapods三方库`以及一些需要添加到`主工程Info.plist`文件内的配置信息 | 详见下表 | + +### config.json配置 + +| 参数 | 用途 | 配置 | +|---|---|---| +| frameworks | 插件依赖的系统库 | 在`主工程`中搜索并添加该列表中的系统依赖库 | +| deploymentTarget | 插件最低支持的iOS版本 | 在`插件工程`中`Target -> General -> Minimum Deployments`设置（若大于主工程设置的最低iOS版本需要同步修改主工程的最低支持） | +| dependencies-pods | 依赖的pod库 | 将其添加到`插件工程`的`Podfile`文件中并执行`pod install` | +| plists | 需要添加到原生主工程`Info.plist`中的配置文件 | 将字段配置添加到`主工程`的`Info.plist`中 | +| hooksClass | 用于uts插件应用程序生命周期函数监听 | 在`插件工程`中找到上面创建的`uts-config.json`文件，将该配置内容添加到`hooksClasses`节点下 | +| provider | 组件的注册信息 | 在`插件工程`中找到上面创建的`uts-config.json`文件，将该配置内容添加到`providers`节点下 | +| components | 组件的注册信息 | 在`插件工程`中找到上面创建的`uts-config.json`文件，将该配置内容添加到`components`节点下 | + +`uts-config.json`配置示例图 +![](https://web-ext-storage.dcloud.net.cn/native/doc/iOS/utsconfig.png) + + +## 编译导出xcframework +选择构建目标(Any iOS Device/Any iOS Simulator Device)，在菜单栏中，选择`Product -> Build`（或使用快捷键`Command + B`），分别编译出真机以及模拟器的Framework文件。 +在菜单栏中，选择`Product -> Show Build Floder in Finder` 获取编译产物所在路径。 +使用xcodebuild命令行创建xcframework +``` +xcodebuild -create-xcframework -framework 真机路径/unimoduleUniGetbatteryinfo.framework -framework 模拟器路径/unimoduleUniGetbatteryinfo.framework -output 导出路径/unimoduleUniGetbatteryinfo.xcframework +``` +导出成功后，将 `unimoduleUniGetbatteryinfo.xcframework` 添加到主工程，并设置为 `Embed && Sign` + +> 编译模拟器注意事项 +> `Apple芯片`的设备编译模拟器需要在菜单栏中点击 `Product -> Destination -> Show All Run Destinations` ，然后选择 `Rosetta模拟器` 编译 \ No newline at end of file