需求

必備知識

  • 了解 AEM Mobile
  • 透過隨選入口網站建立及發佈內容的知識
  • Apache Cordova 相關知識 (http://cordova.apache.org)

必要產品

  • AEM Mobile

Cordova 擴充性

Experience Manager Mobile Runtime 可讓用戶使用 Apache Cordova 擴充性建立豐富的應用程式體驗,並且運用開發人員工具 (測試版) 進行測試。

Cordova 擴充性 (適用於 HTML 文章以及 InDesign 文章的網頁覆蓋) 可讓您存取下列功能:

  • 核心 Cordova 增效模組 – 利用核心 Cordova 增效模組,例如相機、連絡人、地理位置和檔案共用。
  • 自訂 Cordova 增效模組 – 使用來自 Cordova/Phonegap 社群的增效模組或建立您自己的增效模組。範例:條碼掃描及行動資料庫。
  • AEM Mobile 專用的增效模組 (透過 Cordova 啟用) – 本機應用程式和內容中繼資料的增效模組。

 

核心 Cordova 增效模組

這組核心 Cordova 增效模組可讓您使用 JavaScript,在 AEM Mobile 內容檢視中存取原生裝置功能。您可以在建立應用程式時,針對不同的應用程式啟用或停用增效模組。

目前有下列核心 Cordova 增效模組可供使用:

  • 相機 – 用於拍攝照片以及從系統的影像庫中選擇影像。
  • 連絡人 – 可存取裝置連絡人資料庫。對於 Windows 應用程式,增效模組唯一支援的 API 是「pickContact」。
  • 裝置資訊 – 說明裝置硬體和軟體。
  • 裝置動作 (加速計) – 可存取動作感應器,以便偵測相對於目前裝置方向的動作變更 (以 X、Y 和 Z 軸的三維座標表示)。
  • 裝置方向 (羅盤) – 偵測裝置所指方向的感應器,通常位於裝置的頂端。
  • 檔案存取 – 允許讀取/寫入位於裝置上的檔案。
  • 檔案傳輸 – 允許上傳和下載檔案。
  • 地理位置 – 提供有關裝置位置的 GPS 資訊,例如緯度和經度。
  • 全球化 – 針對用戶的地區設定、語言和時區使用特定的作業。
  • 媒體 (cordova-增效模組-媒體) – 能夠在裝置上錄製及播放音訊檔案。
  • 媒體擷取 – 可存取裝置的音訊、影像和視訊擷取功能。
  • 網路資訊 – 有關裝置行動網路和 Wi-Fi 連線的資訊,以及裝置是否具有網際網路連線。
  • 通知對話框 – 可存取某些原生對話框 UI 元素,例如警告和嗶嗶聲。
  • 震動 (僅限 iOS、Android) – 震動裝置的方式。
  • WKWebView (僅限 iOS) – 您可以啟用 WKWebView 增效模組,以便透過 Mobile Safari 的相同呈現方式,呈現 HTML 檔案。這個選項會針對 iOS 9 裝置上的 HTML 文章和網頁覆蓋使用 WKWebView (WebKit) 而非 UIWebView。在 iOS 8 裝置上執行的應用程式仍然會使用 UIWebView 來呈現內容 (請參閱「建立適用於 AEM Mobile 的 iOS 應用程式」)。

如需詳細資訊,請參閱「Cordova 核心增效模組」。

如需範例,請參閱「從 Github 下載範例」。

自訂 Cordova 增效模組

藉由新增自訂 Cordova 增效模組至 AEM Mobile 應用程式,您建立的內容可使用許多來自 Cordova/PhoneGap 社群的增效模組,或者您也可以建立自己的自訂增效模組。例如,您可以在您的應用程式中啟用行動條碼掃描、存取地理柵欄,以及運用行動資料庫。

建立使用自訂 Cordova 增效模組之應用程式的工作流程,不同於標準的建立應用程式方法。您使用更新的 AEM Mobile Developer Tool 來指定您想要使用的 Cordova 增效模組。如果是 iOS 應用程式,則使用開發人員工具來修改下載的 .ipa。如果是 Android 應用程式,則使用開發人員工具建立 .apk 檔案,然後使用新的「自訂應用程式殼層」索引標籤上傳檔案,此索引標籤在建立或編輯 Android 應用程式時會顯示。

請參閱 https://cordova.apache.org/plugins/

 

註解:

目前,Cordova 增效模組皆限制為文章層級。文章必須開啟,才能讓 AEM Mobile 應用程式使用增效模組。對於 iOS 裝置,如果文章是頂層系列中的第一個項目,該文章會在應用程式啟動時載入,並且會保留在記憶體中。該文章可以繼續執行,並且會在用戶瀏覽至其他內容後,進行相同的 Cordova 增效模組呼叫。不過,在該頂層文章中的增效模組無法供其他文章參照。

 

AEM Mobile 專用的 Cordova 增效模組

AEM Mobile 專用的 Cordova 增效模組是一組 JavaScript API,可讓您在文章內容檢視中存取與 AEM Mobile Runtime 應用程式相關的特定資料及其內容。若要運用 AEM Mobile Cordova 增效模組,您必須在文章屬性中選取「啟用擴充性功能」選項,讓內容啟用擴充性。這些增效模組會在 AEM Mobile 應用程式中自動啟用。

AEM Mobile 專用的 Cordova 增效模組包括下列 API:

  • 實體中繼資料存取 (內容標題、權益)
  • 裝置資訊 (平台、版本、識別碼)
  • 推播通知資訊 (推播 Token)
  • 縮圖 (背景和社交分享影像)

如需詳細的文件,請參閱「使用 AEM Mobile 專用的 Cordova 增效模組」。

Cordova 增效模組範例

在應用程式中啟用擴充性功能

  1. 針對參照 Cordova API 的內容檢視或網頁覆蓋,建立來源 HTML 內容。

    如果您的 HTML 程式碼參照核心 Cordova 增效模組或 AEM Mobile 專用的 Cordova 增效模組,請加入下面這行:

    <script type="text/javascript" src="cordova.js"></script>

    cordova.js 檔案會自動包含在您的應用程式中;您只需要在執行階段載入即可。

    Cordova 增效模組和 AEM Mobile 專用的 Cordova 增效模組都需要 Cordova 完全載入之後,才能安全使用。否則,呼叫特定 Cordova API 的指令碼可能會失敗,因為 Cordova 尚未載入。

    當 Cordova 就緒時,它會觸發 deviceready 事件,可讓您用來判斷啟動程式碼的時機。

    在您的 HTML 檔案中包含這個程式碼︰

    document.addEventListener("deviceready", function() {
        // Cordova is now ready,
        // start initializing the rest of the code
    }, false);

    如需詳細資訊,請參閱「Cordova 事件」。

  2. 對於使用這些增效模組的每個內容,在內容屬性中選取「啟用擴充性功能」(在隨選入口網站的「內容與版面」區段中,編輯內容屬性)。

    您也可以透過 On-Demand Services API 針對文章啟用擴充性功能。建立或更新文章實體中繼資料時,請將 isTrustedContent 參數設定為 true (布林值)。此值預設為 false。

    所有文章預設是關閉「啟用擴充性功能」。您可以在專案設定中變更預設值。

  3. 如果是使用核心 (而非自訂) Cordova 增效模組的應用程式,請建立啟用 Cordova 增效模組的應用程式 (如果是自訂 Cordova 增效模組,請依照下一節中的步驟執行)。

    在建立應用程式時使用「增效模組」索引標籤,以便啟用您要在內容中使用的 API。

    AEM Mobile 專用的 Cordova 增效模組不需要另外啟用增效模組。

    iOS 應用程式的增效模組

    註解:

    為獲得最佳效果,請只選取您計劃要使用的 Cordova 增效模組。

  4. 測試應用程式。

建立使用自訂 Cordova 增效模組之應用程式的工作流程

如果您在應用程式中使用自訂 Cordova 增效模組,需要使用 AEM Mobile Developer Tool 來指定使用的 Cordova 增效模組。然後,您使用開發人員工具修改 .ipa 檔案 (iOS),或者建立 .apk 應用程式殼層 (Android) (在建立 Android 應用程式時可以上傳)。

這些步驟只有在您想要在應用程式中使用自訂 Cordova 增效模組時才需要。使用開發人員工具來指定您應用程式中使用的所有增效模組 (自訂、核心和 AEM Mobile 專用)。當您使用開發人員工具修改或建立應用程式時,所有在建立應用程式時於「增效模組」索引標籤中指定的設定都會被忽略。使用開發人員工具來指定所有 Cordova 增效模組資訊。

自訂 Cordova 增效模組影片

自訂 Cordova 增效模組影片

使用自訂 Cordova 增效模組之應用程式的 iOS 工作流程

  1. 建立使用 Cordova 增效模組的內容。依照「在應用程式中啟用擴充性功能」中的上述步驟,在每個使用 Cordova 增效模組的文章中允許擴充性。

  2. 在隨選入口網站中,建立 iOS 應用程式,並下載 .ipa 檔案 (請參閱「建立適用於 AEM Mobile 的 iOS 應用程式」)。

  3. 使用 AEM Mobile Developer Tool 來設定專案、測試您的內容,以及識別在應用程式中使用的 Cordova 增效模組。然後,使用開發人員工具修改下載的 .ipa 檔案,使其包含您所指定的 Cordova 資訊。

    如需詳細資訊,請參閱以下說明如何使用 AEM Mobile Developer Tool 的章節。

  4. 簽署已修改的 .ipa 檔案。

使用自訂 Cordova 增效模組之應用程式的 Android 工作流程

  1. 建立使用 Cordova 增效模組的內容。依照「在應用程式中啟用擴充性功能」中的上述步驟,在每個使用 Cordova 增效模組的文章中允許擴充性。

  2. 使用 AEM Mobile Developer Tool 來設定專案、測試您的內容,以及指定您計劃要在應用程式中使用的 Cordova 增效模組。然後,使用開發人員工具建立應用程式殼層 (.apk 檔案),其中包含您所指定的 Cordova 資訊。

    如需詳細資訊,請參閱以下說明如何使用 AEM Mobile Developer Tool 的章節。

  3. 在隨選入口網站中,建立 Android 應用程式。在「自訂應用程式殼層」索引標籤中,指定您使用開發人員工具建立的 .apk 檔案。

  4. 在隨選入口網站中,下載並簽署 .apk 檔案。

使用 AEM Mobile Developer Tool

AEM Mobile Developer Tool 是一種命令列公用程式,可讓開發人員工作流程更加順暢。此工具會安裝在開發人員的本機桌面上,而且提供下列功能:

  • 建立專案 – 建立可供本機開發的 AEM Mobile 專案檔案夾結構。這個專案結構只能用於測試。
  • 建立內容 – 建立 AEM Mobile 內容範本,此範本可利用可用的 Cordova 和 Runtime API。
  • 新增 Cordova 增效模組並建立應用程式 – 如果您在應用程式中使用自訂 Cordova 增效模組,需要使用開發人員工具來指定增效模組,並建立應用程式殼層 (Android) 或修改 .ipa 檔案 (iOS),其中包含您所指定的 Cordova 增效模組。
  • 在模擬器上執行 – (1) 啟動模擬器、(2) 安裝模擬器組建版本,然後 (3) 啟動會顯示本機環境之本機內容的 AEM Mobile Runtime 模擬器組建版本。如果已啟動目標模擬器,就會忽略步驟 1;如果已安裝模擬器組建版本,就會忽略步驟 2。
  • 說明 – 顯示命令列命令的說明。

AEM Mobile 命令結構

AEM Mobile Developer Tool 是兩個主要工作流程的必要工具:

  • 開發和測試使用 Cordova 增效模組的內容。
  • 建立包含自訂 Cordova 增效模組的應用程式。

 

授權合約

註解:

一旦安裝下列軟體,即表示我確認已閱讀並同意 Adobe.com 使用條款的規定。

安裝相關工具

請依據作業系統來安裝所需的相關工具:

  • Mac OS X:
    • Node JS (建議使用目前版本,需要 v6.2.2 或更新版本)
    • 對於 iOS 開發,請安裝 Xcode (v7.0 或以上版本)
    • 對於 Android 開發,請安裝 Java (視 OS X 版本而定)
  • Windows:

 

安裝 AEM Mobile 命令列工具 (Mac OS)

在 Windows 上開發時,請在 PowerShell 中執行所有命令,而非在命令提示字元中執行。

  1. 啟動「終端機介面」。

  2. 執行下列命令以透過 Node.js 安裝 AEM Mobile 命令列工具:

    npm install -g aemm

    如果出現用戶權限遭拒的訊息,請嘗試使用「sudo」來執行上述指令碼:

    sudo npm install -g aemm

    一旦完成之後,就會建立符號連結,讓您可以在「終端機介面」的任何目錄中執行 AEM Mobile 命令列工具 (aemm)。

更新開發人員工具

每當 AEM Mobile Developer Tool 有更新版本可用時,重新執行 npm install -g aemm (或 sudo npm install -g aemm)。

設定適用於 Android 的環境

若要模擬 Android 組建版本,您必須安裝必要的 Android SDK,並設定用來執行 Android 模擬器的環境。

  1. 在「終端機介面」中,執行下列命令以安裝必要的 SDK 和設定:

    aemm platform install android
  2. 系統可能會詢問您是否接受 Android SDK 授權合約。請輸入 y 接受合約或輸入 n 拒絕合約。如果拒絕,您將無法安裝必要的 SDK 並執行 Android 模擬器。

只有在建立使用自訂 Cordova 增效模組的應用程式時,才需要設定適用於 iOS 的環境 (sudo aemm platform install ios)。

安裝模擬器組建版本

AEM Mobile 命令列工具需要 AEM Mobile Runtime 模擬器組建版本,它將在建立專案時安裝及執行。測試使用模擬器的 HTML 內容時,需要這個程序。建立使用自訂 Cordova 增效模組的應用程式時,則不需要它。

若要安裝 AEM Mobile Runtime 模擬器組建版本,請執行下列任一項作業:

  1. 在「終端機介面」中,執行下列命令以安裝最新版的模擬器組建版本:

    aemm app install <platform>

    可用的 <platform> 值如下:iosandroid

或者,您也可以指定模擬器組建版本。這樣做可讓您根據可用的模擬器組建版本清單安裝舊版本。

  1. 在「終端機介面」中,取得可用的模擬器版本清單:

    aemm app install --list
  2. 在安裝程序中指定模擬版本︰

    aemm app install <platform> <simulator-version>

    例如,在 iOS 上安裝模擬器版本 2016.4:

    aemm app install ios 2016.4

    註解:

    如果您在嘗試執行模擬器時出現錯誤訊息,請啟動 Xcode 並簽署授權合約 (如果情況合適)。您也可以在「終端機介面」中輸入 sudo xcodebuild –license accept

     

建立專案

AEM Mobile 命令列工具具有建造及測試專案所需的目錄結構。這個專案僅供測試之用。測試內容之後,您可以將內容新增至隨選入口網站上的專案。

若要設定此專案,請執行下列動作:

  1. 在「終端機介面」中,瀏覽至您想要用來管理新專案的目錄。
  2. 建立目錄結構 (以您的專案名稱取代「<project name>」):
aemm project create <project-name>

這樣就會使用指定的 <project-name> 建立目錄並且在該目錄內建立名為「SampleArticle」的範例內容目錄。

執行模擬器

現在專案目錄已建立完成,您可以開始建立應用程式了。測試使用模擬器的 HTML 內容時,需要這個程序。建立使用自訂 Cordova 增效模組的應用程式時,則不需要它。

若要開啟模擬器 (如果尚未開啟)、安裝 AEM Mobile Runtime 模擬器組建版本 (如果尚未安裝) 及執行模擬器,請執行下列動作:

  1. 在「終端機介面」中,使用下列命令瀏覽至已建立的專案目錄:

    cd <drag and drop the project-name directory>
  2. (選擇性) 設定模擬器啟動時的預設方向。選項包括橫向或縱向模式。

    aemm config --set screenOrientation <<orientation>>

    例如,將方向指定為橫向模式:

    aemm config --set screenOrientation landscape

    使用這個命令也會取代現有的預設方向模式 (若有的話)。若要取得目前的預設方向模式:

    aemm config --get screenOrientation

    若要移除目前的預設方向模式:

    aemm config --unset screenOrientation
  3. 開啟、安裝及執行模擬器組建版本。

    aemm run <platform>

    可用的 <platform> 值如下:iosandroid

  4. 此執行命令將會在終端機介面中持續接聽,若要終止此程序,請在同一個終端機介面視窗中輸入下列按鍵組合:Ctrl + C

一旦模擬器應用程式啟動之後,您應該能夠看見先前建立的「SampleArticle」。如果對「SampleArticle」目錄內的檔案進行變更,都會導致模擬器應用程式重新整理並自動顯示更新的內容。

當執行模擬器時,按 Command+Shift+H 可返回主畫面。

您可以透過指定裝置名稱,指定要使用的模擬器裝置。在不同的模擬器裝置上測試時,這樣做很方便。

  1. 取得目前安裝在系統中的可用模擬器清單:

    aemm run <platform> --list
  2. 根據 <uuid><device-name> 清單,指定裝置:

    aemm run <platform> --target "<device-name>"

    例如,在安裝 iOS 9.2 的 iPhone 6s 上執行模擬器:

    aemm run ios --target "iPhone-6s, 9.2"

建立內容

專案會建立預設的 HTML 內容範本,但是您可以透過執行下列動作,將更多內容新增至清單:

  1. 在「終端機介面」中,瀏覽至已建立的專案目錄:

     cd <drag and drop the project-name directory>
  2. 建立其他 HTML 內容:

    aemm article create <article-name>

    這樣就會在專案目錄內使用指定的 <article-name> 建立另一個 HTML 內容目錄。

    HTML 內容檔案夾結構只是一個包含 index.html 的目錄,而且所有必要的資源 (CSS/JS/影像/其他) 都透過 index.html 詳細配置。因此,您也可以直接在 <project-name directory>/www/<custom-folder> 內建立一個檔案夾,然後加入 index.html,而非執行上述指令碼。如果您的 HTML 內容已經收錄在其他地方而且想要測試 Cordova 擴充性,這樣做可能很有用。您可以將 HTML 內容拖放到 <project-name directory>/www/ 檔案夾中,然後模擬器就會自動辨識內容。

將 Cordova 增效模組新增至專案 (適用於自訂 Cordova 增效模組)

這些命令只有在您想要在應用程式中使用自訂 Cordova 增效模組時才需要。如果您使用自訂 Cordova 增效模組,需要使用 AEM Mobile Developer Tool 來指定您應用程式中使用的 Cordova 增效模組 (自訂、核心和 AEM Mobile 專用)。

  1. 請確定 Node JS v6.2.2 或更新版本已安裝。

    如果您先前已安裝 LTE 版本,我們建議您下載並安裝目前的版本。

  2. 在「終端機介面」中,瀏覽至已建立的專案目錄:

    cd <drag and drop the project-name directory>
  3. 新增要包含在應用程式中的 Cordova 增效模組 (核心和自訂):

    aemm plugin add [plugin_0] [plugin_1] [...]

    若要啟用 AEM Mobile 應用程式中使用的標準 Cordova 增效模組:

    aemm plugin add aemm-plugin-application aemm-plugin-user aemm-plugin-context aemm-plugin-device aemm-plugin-inappbrowser aemm-plugin-fullscreen-video aemm-plugin-navto aemm-plugin-html-contract

    若要將預設值從 UIWebView 變更為 WKWebView (與在「增效模組」索引標籤中選取「WKWebView」的結果相同):

    aemm plugin add https://github.com/adobe-marketing-cloud-mobile/cordova-plugin-wkwebview-engine.git#2.0.0

    目前使用的是版本 2.0.0,但可能會更新。您可以在這裡找到最新版本:https://github.com/adobe-marketing-cloud-mobile/cordova-plugin-wkwebview-engine/releases

    若要啟用 AEM Mobile 應用程式中使用的所有核心 Cordova 增效模組 (移除您不想要使用的增效模組):

    aemm plugin add cordova-plugin-camera cordova-plugin-compat cordova-plugin-contacts cordova-plugin-device cordova-plugin-device-motion cordova-plugin-device-orientation cordova-plugin-dialogs cordova-plugin-file cordova-plugin-file-transfer cordova-plugin-geolocation cordova-plugin-globalization cordova-plugin-media cordova-plugin-media-capture cordova-plugin-network-information cordova-plugin-vibration

    使用這個命令來檢視新增至專案的增效模組清單:

    aemm plugin list

    使用這個命令移除先前加入的增效模組:

    aemm plugin remove [plugin]

    使用 help 命令檢視其他資訊:

    aemm plugin help

建立自訂應用程式 (適用於自訂 Cordova 增效模組)

這些命令只有在您想要在應用程式中使用自訂 Cordova 增效模組時才需要。 

如果是 iOS 應用程式,需要修改您從隨選入口網站的「應用程式」區段下載的 .ipa 檔案。

如果是 Android 應用程式,需要建立應用程式殼層 .apk 檔案,在隨選入口網站上建立應用程式時可以上傳此檔案。

請注意,在建立應用程式時於「增效模組」區段中指定的任何設定都會被忽略,並取代為使用 AEM Mobile Developer Tool 所指定的設定。

註解:

「aemm」命令是建立在「cordova」命令之上,會委派許多命令至 cordova-lib。您可能會遇到錯誤並建議您嘗試執行 cordova 命令。在大多數情況下,請先嘗試將 cordova 取代為 aemm,然後執行建議的動作。

  1. (iOS) 設定 iOS 環境,讓 Xcode 建立未簽署的架構。

    sudo aemm platform install ios
    aemm platform add ios
  2. 瀏覽至建立的專案目錄,並新增要內含在應用程式中的 Cordova 增效模組,如上一節所述。

  3. 建立 Cordova 結構 (iOS) 或建立應用程式殼層 (Android)。

    aemm build [platform]

    iOS 範例:

    aemm build ios --device --release

    新增 --device 會建立 iOS 裝置適用的應用程式,而不是模擬器。

    新增 --release 會建立發行版本,而不是預設除錯版本。

    Android 範例:

    aemm build android --release

    註解:

    如果您無法建立應用程式,我們建議您解除安裝 NodeJS,然後安裝目前版本的 NodeJS (如需詳細資訊,請參閱 NodeJS 網站)。此外,執行 sudo npm uninstall -g aemm,然後執行 sudo npm install -g aemm

    解決程式碼簽署錯誤訊息

    如果您已更新 XCode,可能會出現下列錯誤訊息:「Error: CODE_SIGNING_REQUIRED must be set to NO in order to build for device. You can resolve this by running 'aemm platform install ios'」。

    如果您遇到此問題,因應措施是在「終端機介面」中執行下列命令:

     

    sudo /usr/libexec/PlistBuddy -c "Set DefaultProperties:CODE_SIGNING_REQUIRED NO" "$(xcode-select -p)/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/SDKSettings.plist"

    每次更新 Xcode 後都必須執行此因應措施。

  4. (iOS) 封裝 .ipa 檔案。

    aemm package ios --device <drag and drop .ipa file>

    範例:

    aemm package ios --device /Users/jdoe/Downloads/coffee_2062.ipa
  5. 執行下列其中一個動作:

    • (iOS) 簽署已修改的 .ipa 檔案。
    • (Android) 上傳您在隨選入口網站上建立的 .apk 應用程式殼層。建立、下載並簽署 .apk 檔案。

    如需此工作流程的詳細資訊,請參閱本文前面章節,其中說明如何建立使用自訂 Cordova 增效模組的應用程式。

在模擬器中測試自訂 Cordova 增效模組

執行下列命令:

aemm build ios
aemm package ios
aemm run ios

省略 --device 參數,將命令套用至模擬器。需要執行 aemm package ios,才能將自訂增效模組封裝到模擬器組建版本。若要還原原始模擬器組建版本,請重新執行 aemm app install ios 命令。

遠端偵錯

您可以透過模擬器從遠端檢測 HTML 內容,就像使用現代瀏覽器一樣。這項功能可讓您查看及操作 DOM 元素、檢查主控台產生的任何錯誤或直接輸入 JavaScript/jQuery 命令,以及進行其他作業。如需詳細資訊,請參閱下列文件︰

封裝內容

專案目錄內的 HTML 內容也會採用必要的結構,以便針對 AEM Mobile 隨選服務入口網站產生內容檔案。您可以選取專案目錄內的所有 HTML 內容,然後將它們拖放到 AEM Mobile Packager 中。

如需詳細資訊,請參閱「建立適用於 AEM Mobile 的 HTML 文章」。

此産品由 Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License 授權  Creative Commons 條款未涵蓋 Twitter™ 與 Facebook 文章。

法律說明   |   線上隱私權政策