安裝說明

Android

環境設置

您可以使用 Windows、Mac 或 Linux 桌面作業系統作為開發環境。請在系統中安裝好最新的 Android Studio 開發工具與 Android SDK（會在 Android Studio 安裝過程中一併安裝）。

準備好一台或多台 Android 手機或平板裝置，並開啟「開發者模式」，確保它們能以 USB 連接線方式與開發環境電腦串接，並可被 Android Studio 辨識。

!!! Warning "注意" 必須注意 arctos links SDK 並不能在模擬器環境運作，因此使用前需準備好 Android 手機或平板。

安裝步驟

arctos links 視訊 SDK ZIP 將包含數個 aar 檔案。請將 aar 檔案移動到您 Android Studio 專案中，app 資料夾內的一個目錄（例如 libs）

編輯 app/build.gradle 檔案，加入對這些 aar 檔案的依賴：

dependencies {
	// 對 arctos links SDK module 的依賴
	implementation fileTree(include: ['*.aar'], dir: 'libs')
}

接著從 File -> Sync Project with Gradle Files 選項，同步整個專案，即可開始開發。

您也可以參考我們提供的範例應用程式。

iOS

事前準備

  • 請確保安裝下列項目：

    • Xcode 15+（版本視蘋果開發者官網各年度 Release 而定）

  • 確認您的專案符合下列規定：

    • 開發者帳號相關：

      • Apple Developer 申請開發帳號，若沒有請至 Apple Developer 官方網站申請，完成後通常為「免費版」開發者帳號

      • 確保您的開發者帳號為「個人付費版」或者「公司組織版」，若為「免費版開發者」本請至 Apple Developer Programs 申請您的「個人付費版」或者申請加入至「公司組織版」下成為團隊內的開發者

    • 您的專案必須指定下列平台版本或更新版本：

      • iOS 14+

      • iPadOS 14+

    • 當前版本尚不支持以下平台：

      • ❌模擬器

      • ❌macOS

      • ❌tvOS

      • ❌watchOS

前置步驟1：Xcode 建立 App 專案

!!! INFO "備註" 若是已存在之舊專案，請跳至 前置步驟2：確認環境設置

以新專案為例，以下為 Xcode 15.2 建立，名稱為 SDKSampleApp 的新專案，如圖：

step1

前置步驟2：確認環境設置

  • 檢查專案 TARGETS -> General 設定

    • Supported Destinations（支援平台）-> iPhone (and iPad)

    • Minimum Deployments（最低部署版本）-> 調整為 iOS 14.0+

    step2-1

    step2-1

  • 檢查專案 TARGETS -> Signing & Capablilties 設定

    • 新增 Background Modes -> ✅Audio, AirPlay, and Picture in Picture

    !!! INFO "備註" SDK 內使用裝置內建麥克風收音功能，啟用 Audio, AirPlay, and Picture in Picture 以允許 App 可以在背景中運行

    step2-3

  • 檢查專案 TARGETS -> Info 設定 -> Custom iOS Target Properties 額外加入以下權限

    • Privacy - Camera Usage Description（相機）

    • Privacy - Microphone Usage Description（麥克風）

    !!! INFO "備註" SDK 內使用裝置內建相機、麥克風收音功能，按照官方 App 設計規範，為了讓 App 能順利運行必須提供相關權限。

    step2-4

安裝方法 - 分為手動 (.zip file)、Swift Package Manager (SPM)，擇一即可

手動（zip file）

  • 取得我司提供 arctos links 視訊 SDK (.zip file) 包含以下 .xcframework 檔案：

    • ArctosLinks.xcframework（主要框架）

      • ArctosCarrier.xcframework（ArctosLinks 依賴框架）

      • libyuv.xcframework（ArctosLinks 依賴框架）

      • RxSwift.xcframework（ArctosLinks 依賴框架）

        • RxCocoa.xcframework（RxSwift 拓展框架，ArctosLinks未使用）

        • RxRelay.xcframework（RxSwift 拓展框架，ArctosLinks未使用）

        • RxTest.xcframework（RxSwift 拓展框架，ArctosLinks未使用）

        • RxBlocking.xcframework（RxSwift 拓展框架，ArctosLinks未使用）

      • CocoaMQTT.xcframework（ArctosLinks 依賴框架）

        • MqttCocoaAsyncSocket.xcframework（CocoaMQTT 依賴框架）

        • Starscream.xcframework（CocoaMQTT 依賴框架）

  • 導入我司所提供的 SDK .xcframwork 二進制檔案，對專案名稱點擊右鍵選單 -> Add Files to "SDKSampleApp"...

    step3-1

  • 選定提供的相關 .xcframework 後，留意勾選 ✅Copy items if needed

    step3-2

  • 加入後請確認 TARGETS -> General -> Frameworks, Libraries, and Embedded Contect，所有新增的 .xcframework 是否都有正確的處於 Embed & Sign 狀態，如圖所示：

    step3-3

Swift Package Manager (SPM)

  • 取得我司提供的以下資訊，可透過 xcode 進行 Swift Package Manager（簡稱 SPM）進行安裝

    • GitLab Domain

    • Account

    • Access Token

    • Project URL

  • 從 Xcode 上方工具列點選 Settings.. -> 點選 Account -> 左下角**＋** -> GitLab self-hosted，如圖所示：

    SPM0

    SPM1

  • 輸入我司提供的 GitLab Domain、Account、Access Token 進行驗證，如圖所示：

    SPM2

    SPM3

  • 點擊專案名稱 .xcproject -> PROJECT -> Package Dependencies -> 左下角**＋**

    SPM4

  • 輸入我司提供 Project URL -> 驗證通過將出現對應之 SDK -> 點擊右下角 Add Package

    SPM5

  • 新增後將會提供許多 Package Product，一般來說選用 ArctosLinks-SPM 加入即可，如圖所示：

    • ArctosLinks-SPM（主要框架）

    • iHH_RxBlocking (可選用，用於解決原專案有使用 RxBlocking 開發者，編譯衝突問題)

    • iHH_RxCocoa (可選用，用於解決原專案有使用 RxBlocking 開發者，編譯衝突問題)

    • iHH_RxRelay (可選用，用於解決原專案有使用 RxBlocking 開發者，編譯衝突問題)

    • iHH_RxTest (可選用，用於解決原專案有使用 RxBlocking 開發者，編譯衝突問題)

    SPM6

    SPM7

初始化 SDK

具體使用方式請參閱章節 使用方法 初始設定

套件管理常見問題

  • 成因

    我司提供的 SDK 方案，皆採用 Carthage 集成，將我司核心技術 ArctosLinks 與其他公開技術等第三方套件預先編譯成 .xcframework 動態二進制套件作管理，ArctosLinks-SPM 也是將 xcframework 打包為 SPM 形式發佈，採用的公開套件如下：

    至於為什麼會使用 .xcframework，是因為這種方式擁有以下優點：

    1. 輕量化且簡單集成

      不將第三方源代碼集成到專案目錄內，不同於 CocoaPods 與 Swift Package Manager，而是相對單純的 .xcframework 檔案，讓開發者以手動的方式，將檔案新增至專案中。

    2. 對 Xcode 環境友善

      不需額外腳本來自動管理依賴（如 Pods.xcodeproj 之類的文件）。可保持 Xcode 專案環境結構簡潔、獨立、減少干擾。

    3. 提升項目編譯建構效率

      .xcframework 是預編譯的二進制庫，代表編譯專案項目時不需重新編譯這些二進制庫，這對有使用多個第三方套件的專案，能顯著提高開發效率、節省構建時間。

    4. 安全性與靜態掃描

      靜態掃描並非針對專案本身，而是取決於項目的應用領域、企業制度、法規等，例如：軍用領域、醫療領域、金融領域...等，為了符合法規，需額外執行靜態掃描驗證代碼安全、是否符合規範。.xcframework 是二進制庫，非源代碼，自然不受靜態掃描規範所影響，開發者在掃描的後續問題處理上相對輕鬆。

    當然 .xcframework 雖有眾多好處，但實際開發上還是有缺點需做出取捨。例如：專案內本身若使用一些第三方套件，這些套件本身依賴於其他的公開套件，就有可能遇到會依賴套件重複引用的問題，假設「套件 A 內部引用 C 套件」、「套件 B 內部引用 C 套件」，A、B 套件各自獨立，但卻同時引用著自己內部 C 套件，這情況就會遇到 C 套件重複引用的編譯問題。其次，重複套件在不同的集成方式下也會造成專案編譯上的困難。

    現在已知的套件集成管理方式至少有 3 種：CocoaPods、Swift Package Manager、Carthage，若是集成方式混用遇到問題，對於開發者來說，要解決就是件相當麻煩的事。為了應對這種狀況，我司額外提供了解決方案供開發者使用。

    此為 RxSwift.xcframework 與 GitHub SPM RxSwift 同時存在，所產生的衍生的編譯、程式執行問題 ⬇️ FAQ-SPM

    FAQ-SPM2

  • CocoaPods、Swift Package Manager 重複套件引用衝突

    請移除 CocoaMQTT、RxSwift 相同名稱的 Pods 相關套件內容，並根據您的安裝方式按照以下指示：

    • 手動 (.zip file)

      1. 若您的原專案也使用了 RxSwift 核心之外的拓展套件如：RxCocoa、RxRelay...等，請根據我司額外所提供的相關對應名稱 Rx____.xcframework 進行額外引用，例如：原先使用到 RxRelay，請額外新增 RxRelay.xcframework 作為替代

    • Swift Package Manager (SPM)

      1. 若您的原專案也使用了 RxSwift 核心之外的拓展套件如：RxCocoa、RxRelay...等，請額外新增 Package Product 相關對應名稱 iHH_Rx____ 進行額外引用，例如：原先使用到 RxRelay，請額外新增 iHH_RxRelay 作為替代

    • CocoaMQTT 套件衝突

      GitHub CocoaMQTT 因源代碼設計有物件命名衝突問題，需額外對其進行調整。

      1. 一樣移除您現有專案內 Pods、SPM 所管理的 GitHub CocoaMQTT

      2. 這步驟需要請開發者手動調整專案代碼，重新命名 CocoaMQTT 物件，將其重新命名為 CocoaMQTT3，範例代碼如下：

      import CocoaMQTT
    
class MQTTAccessTool: NSObject {
	// private var mqtt: CocoaMQTT?  <== 將其更換為 CocoaMQTT3?，如下一行所示
	private var mqtt: CocoaMQTT3?
}
    
extension MQTTAccessTool: CocoaMQTTDelegate { 
	// func mqtt(_ mqtt: CocoaMQTT, didConnectAck ack: CocoaMQTTConnAck) {  <== 將其更換為 CocoaMQTT3?，如下一行所示
	func mqtt(_ mqtt: CocoaMQTT3, didConnectAck ack: CocoaMQTTConnAck) {
	
	}
}

  • 參考文獻

Windows (C++ with Qt6)

專案設置

  1. 安裝 Qt6，可藉由 Qt creator 獲取 prebuilt 或自行編譯
  2. Visual Studio 2022 安裝 Qt Visual Studio Tools 延伸模組
    • 延伸模組 -> 管理延伸模組 -> 瀏覽 -> 搜尋 Qt Visual Studio Tools -> 安裝
  3. 建立 QML 專案
  4. 引入 arctos links Windows SDK (Release Mode)
    • 新增 include directories
    • 新增 additional library directories
    • 加入 SDK/lib 中的 lib 參考 以上步驟可以參考 Visual Studio Demo APP 專案設置。