使用 Scene Viewer 透過 Android 應用程式或瀏覽器在 AR 中顯示互動式 3D 模型

Scene Viewer 是一種沉浸式檢視器，可透過網站或 Android 應用程式提供 3D 和 AR 體驗。Android 行動裝置使用者可透過 Scene Viewer，在自己的環境中輕鬆預覽、放置、查看及互動網站託管的 3D 模型。

大多數 Android 瀏覽器都支援 Scene Viewer。許多 Google 合作夥伴已成功導入 Scene Viewer，穩定支援 3D 和 AR 體驗。Google 搜尋也採用這項技術。

導入方式簡單明瞭：

  • 網頁版服務只需要網頁上格式正確的連結。

  • 應用程式體驗只需要整合幾行 Java 程式碼。

Scene Viewer 執行階段需求

如要透過 Scene Viewer 體驗 AR，使用者必須具備：

  • 搭載 Android 7.0 Nougat (API 級別 24) 以上版本的支援 ARCore 的裝置。
  • 最新版 (近期) 的「Google Play 服務 - AR 適用」。這項服務會自動安裝在絕大多數支援 ARCore 的裝置上，並保持在最新狀態。
  • 最新版本的 Google 應用程式。這款應用程式已預先安裝在裝置上，且在絕大多數支援 ARCore 的裝置上，都會自動保持在最新版本。

如果裝置沒有「Google Play 服務 - AR 適用」或 Google 應用程式，或是安裝的版本過舊，您可以指定備用網址來啟動替代體驗，例如網頁、錯誤訊息或您建構的備用體驗。

支援的用途

預定用途 建議使用的應用程式 優點
透過網站或 Android 應用程式上的按鈕或連結，啟動 3D 模型的原生 AR 檢視畫面。

如果裝置上沒有「Google Play 服務 - AR 適用」， 請順利回溯， 改為在 Scene Viewer 支援的 3D 模式中顯示模型。 		使用明確意圖啟動 Scene Viewer，前往 Google 搜尋套件，然後選擇適當的 mode 設定來顯示 3D 模型。
  • ar_preferred：一律從 AR 檢視器啟動，使用者可手動切換至 3D 檢視器。如果沒有「Google Play 服務 - AR 適用」，系統會順利改為在 3D 檢視器中啟動。
  • 3d_preferred：一律從 3D 檢視器啟動，使用者可手動切換至 AR 檢視器。如果沒有「Google Play 服務 - AR 適用」，使用者就無法切換離開 3D 檢視器。
  • 3d_only：一律只會顯示在 3D 檢視器中，使用者無法切換至 AR 檢視器。
  • 支援盡可能多的裝置。
  • 自動切換回 Scene Viewer 的原生 3D 模式，適用於非 AR 用途。
透過網站或 Android 應用程式中的按鈕或連結，啟動 3D 模型的原生 AR 檢視畫面。

如果裝置上沒有「Google Play 服務 - AR 適用」，請控管備援行為。 		使用明確意圖啟動 Scene Viewer，以「Google Play 服務 - AR 適用」(ARCore) 顯示 3D 模型，並選擇適當的mode設定。
  • ar_preferred：一律從 AR 檢視器啟動，使用者可手動切換至 3D 檢視器。如果沒有「Google Play 服務 - AR 適用」，Scene Viewer 會改用您設定的行為。
  • ar_only：一律只在 AR 檢視器中顯示，無法切換至 3D 檢視器。如果沒有 Google Play 服務 - AR 適用，則會回溯至您設定的行為。舉例來說，您可以啟動自己的全螢幕 3D 體驗，或是顯示友善的錯誤訊息，指出使用者的裝置尚未支援 AR 功能。
 使用自己的 3D 模型檢視器，或為非 AR 用途提供您自行設計的其他備用回應。
在網站上代管 3D 模型的內嵌檢視畫面，並允許使用者手動進入全螢幕原生 AR 模式。 使用 <model-viewer> 或任何其他網頁型 3D 檢視器，啟動 Scene Viewer，以 AR 模式原生顯示 3D 模型。
  • 直接從網頁中嵌入的 3D 模型，以 AR 模式啟動 Scene Viewer。
  • 在您擁有及控管的介面上，為使用者提供 3D 體驗，並在您瞭解使用者意圖後，選擇逐步將他們帶入更身歷其境的擴增實境體驗。

使用明確意圖啟動 Scene Viewer (3D 或 AR)

為支援各種 Android 裝置，請使用明確的 Android Intent 啟動 Scene Viewer。您可以從 HTML 網頁或原生 Android 應用程式觸發明確意圖。意圖會由 ARCore 支援的 Android 裝置預先安裝的 Google 應用程式處理。

視設定的意圖參數和裝置功能而定，互動式 3D 模型可放置在使用者環境中，或在 3D 檢視器中顯示。

  • 如果裝置已安裝最新版的「Google Play 服務 - AR 適用」，Scene Viewer 就會以 AR 原生檢視畫面或 3D 檢視畫面顯示模型。

  • 如果沒有「Google Play 服務 - AR 適用」或版本過舊，Scene Viewer 會改為在 3D 檢視畫面中顯示模型。

  • 如果無法顯示 3D 模型 (例如未安裝 Google 應用程式或應用程式版本過舊)，系統會改用 S.browser_fallback_url 參數顯示備用網頁。

透過 HTML 或 Java 啟動 Scene Viewer

HTML

如要從 HTML 觸發明確意圖，請使用下列語法：

<a href="intent://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;S.browser_fallback_url=https://developers.google.com/ar;end;">Avocado</a>

Java

如要從 Java 觸發明確意圖，請使用下列程式碼：

Intent sceneViewerIntent = new Intent(Intent.ACTION_VIEW);
sceneViewerIntent.setData(Uri.parse("https://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"));
sceneViewerIntent.setPackage("com.google.android.googlequicksearchbox");
startActivity(sceneViewerIntent);

意圖版本管理

意圖版本會以 arvr.google.com/scene-viewer 後的版本號碼表示。舉例來說，初始版本使用 1.0 版。如果需要較新的 Scene Viewer 功能，您可以啟動 Scene Viewer，並使用對應所需功能的較高意圖版本。

意圖 1.1 版新增了 intent:// 連結支援，可直接啟動 Android 應用程式，而非前往網址。如果您希望 Scene Viewer 啟動時保證提供這項功能，否則啟動失敗，請使用意圖啟動 Scene Viewer intent://arvr.google.com/scene-viewer/1.1。

支援的意圖參數

系統支援下列參數，可明確指定意圖為 Google 搜尋套件。

意圖參數 接受的值 註解
file (必填) 有效網址 這個網址會指定應載入 Scene Viewer 的 glTF 或 glb 檔案。這個值應經過網址逸出處理。
S.browser_fallback_url (HTML 意圖必須提供) 有效網址 這項 Google Chrome 功能僅支援網頁式實作。 如果裝置上沒有 Google 應用程式，Google Chrome 會前往這個網址。
mode (非必要) 3d_preferred (預設) Scene Viewer 會以 3D 模式顯示模型，並提供「在你的空間中檢視」按鈕。



如果裝置上沒有「Google Play 服務 - AR 適用」，系統會隱藏「在空間中查看」按鈕。

3d_only 即使裝置上已安裝「Google Play 服務 - AR 適用」，Scene Viewer 仍會啟動並以 3D 模式顯示模型。系統一律不會顯示「在你的空間中檢視」按鈕。

ar_preferred Scene Viewer 會以 AR 原生模式做為進入模式啟動。使用者可以透過「在實體空間觀看」和「以 3D 模式觀看」按鈕，在 AR 和 3D 模式之間切換。



如果沒有 Google Play 服務 - AR 適用，Scene Viewer 會順利切換回 3D 模式做為進入模式。

ar_only 使用這個值時，您應透過明確的 Android 意圖啟動，以 com.google.ar.core 為目標。

注意：透過明確的 Android Intent 啟動 Google 應用程式時，請勿使用 ar_only 模式。

link (非必要) 有效網址 外部網頁的網址。如果存在，UI 中會顯示按鈕，點選後會前往這個網址。
title (非必要) 有效字串 模型的名稱。如有提供，就會顯示在使用者介面中。 名稱超過 60 個字元時，系統會截斷並加上省略號。

音效 (選填) 有效網址 與 glTF 檔案中內嵌的第一個動畫同步的循環音軌網址。應與長度相符的動畫 glTF 一併提供。如有，則會在模型載入後循環播放。這個值應經過網址逸出處理。
resizable (非必要) true (預設)

false

 如果設為 false，使用者就無法在 AR 體驗中縮放模型。在 3D 體驗中，縮放功能可正常運作。
enable_vertical_placement (非必要) false (預設)

true

 設為 true 時，使用者就能將模型放置在垂直表面上。

使用者體驗指南

為提供最佳使用者體驗，建議您在顯示的號召性動作中，傳達使用者即將進入沉浸式環境的訊息。

如果是 3D 檢視器體驗，建議使用標示為「在 3D 模式下查看」的號召性動作，如下圖所示：

使用明確意圖啟動「Google Play 服務 - AR 適用」的 Scene Viewer (僅限 AR 模式)

Scene Viewer 的 AR 模式是由「Google Play 服務 - AR 適用」提供技術。

如要確保 Scene Viewer 支援 AR，您可以從網站或原生 Android 應用程式使用明確的 Android Intent，透過 com.google.ar.core package 啟動 Scene Viewer，並提供 browser_fallback_url。這樣一來，您就能確保所有使用者都能透過 Scene Viewer 獲得原生 AR 體驗，或是您自行建構的備用體驗。舉例來說，您可以建構備援體驗，例如自己的 3D 檢視器或優雅的錯誤訊息。

如要從 HTML 觸發明確意圖，請使用下列語法：

<a href="intent://arvr.google.com/scene-viewer/1.0?file=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf&mode=ar_only#Intent;scheme=https;package=com.google.ar.core;action=android.intent.action.VIEW;S.browser_fallback_url=https://developers.google.com/ar;end;">Avocado</a>;

如要從 Java 觸發明確意圖，請使用下列程式碼：

Intent sceneViewerIntent = new Intent(Intent.ACTION_VIEW);
Uri intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.0").buildUpon()
    .appendQueryParameter("file", "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf")
    .appendQueryParameter("mode", "ar_only")
    .build();
sceneViewerIntent.setData(intentUri);
sceneViewerIntent.setPackage("com.google.ar.core");
startActivity(sceneViewerIntent);

支援的意圖參數

Google Play 服務 - AR 適用套件的明確意圖支援下列參數。

意圖參數 接受的值 註解
browser_fallback_url (HTML 意圖必須提供) 有效網址 這項功能僅支援以網頁為基礎的實作方式。 如果裝置上沒有「Google Play 服務 - AR 適用」或不是最新版本，系統就會導向這個網址。
mode (非必要) ar_only Scene Viewer 一律會在原生 AR 檢視畫面中啟動 3D 模型，並隱藏任何用於切換至 Scene Viewer 3D 檢視器的 UI。

如果沒有「Google Play 服務 - AR 適用」，Scene Viewer 會啟動您在 browser_fallback_url 中設定的網址，提供網頁版體驗。 如果是以應用程式為基礎的體驗，Scene Viewer 會改用替代體驗，例如錯誤訊息或您自行建構的其他體驗。
ar_preferred Scene Viewer 會以 AR 原生模式做為進入模式，並提供「在實體空間觀看」和「以 3D 模式觀看」按鈕，讓使用者在 AR 和 3D 模式之間切換。

如果沒有「Google Play 服務 - AR 適用」，Scene Viewer 會啟動您在 browser_fallback_url 中設定的網址，提供網頁版體驗。 如果是以應用程式為基礎的體驗，Scene Viewer 會改用替代體驗，例如錯誤訊息或您自行建構的其他體驗。

   

link (非必要) 有效網址 外部網頁的網址。如果存在，UI 中會顯示按鈕，點選後會前往這個網址。



1.1 版新增了對 Scene Viewer 中 intent:// 連結的支援，讓 Scene Viewer 的造訪按鈕可直接觸發其他應用程式。請注意，使用這項屬性時務必謹慎，且只有在保證特定意圖有對應的意圖處理常式時，才應指定這項屬性。
title (非必要) 有效字串 模型的名稱。如有提供，就會顯示在使用者介面中。 名稱超過 60 個字元時，系統會截斷並加上省略號。



1.1 版新增支援標題內容的 HTML 樣式，且允許任意數量的文字。請注意，標題應經過網址逸出。
sound (非必要) 有效網址 與 glTF 檔案中內嵌的第一個動畫同步的循環音軌網址。應與長度相符的動畫 glTF 一併提供。如有，則會在模型載入後循環播放。
resizable (非必要) true (預設)

false

 如果設為 false，使用者就無法在 AR 體驗中縮放模型。在 3D 體驗中，縮放功能可正常運作。
disable_occlusion (非必要) false (預設)

true

 如果設為 true，放置在場景中的物件一律會顯示在場景中的實體物件前方。詳情請參閱 [啟用遮蔽](/ar/develop/depth#enable_occlusion)。

使用者體驗指南

為提供最佳使用者體驗，建議您遵循這些指南。

  • 如果是 AR 體驗，可見的號召性動作應傳達使用者即將進入沉浸式環境。建議您使用「在空間中查看」號召性行動：

  • 使用者可能未在裝置上安裝 Google Play 服務 - AR 適用。以下說明 <model-viewer> 如何處理備援，您可以放心使用該程式碼片段做為起點。

    // Check whether this is an Android device.
const isAndroid = /android/i.test(navigator.userAgent);
// This fallback URL is used if the Google app is not installed and up to date.
const fallbackUrl = 'https://arvr.google.com/scene-viewer?file=https%3A%2F%2Fstorage.googleapis.com%2Far-answers-in-search-models%2Fstatic%2FTiger%2Fmodel.glb&link=https%3A%2F%2Fgoogle.com&title=Tiger';

// This intent URL triggers Scene Viewer on Android and falls back to
// fallbackUrl if the Google app is not installed and up to date.
const sceneViewerUrl = 'intent://arvr.google.com/scene-viewer/1.0?file=https://storage.googleapis.com/ar-answers-in-search-models/static/Tiger/model.glb&title=Tiger#Intent;scheme=https;package=com.google.android.googlequicksearchbox;action=android.intent.action.VIEW;S.browser_fallback_url=' +
    fallbackUrl + ';end;';

// Create a link.
var a = document.createElement('a');
a.appendChild(document.createTextNode('Tiger'));
// Set the href to the intent URL on Android and the fallback URL
// everywhere else.
a.href = isAndroid ? sceneViewerUrl : fallbackUrl;
// Add the link to the page.
document.body.appendChild(a);

使用 <model-viewer> 啟動 Scene Viewer

如要從網站啟用 Scene Viewer，請加入 <model-viewer> 網頁元件和 ar 屬性。

<model-viewer ar
              ar-modes="scene-viewer webxr quick-look"
              alt="A 3D model of an astronaut."
              src="Astronaut.gltf"></model-viewer>

在支援 ARCore 的 Android 裝置上查看時，包含 ar 元件和 ar 屬性的網站會顯示按鈕，如下列範例所示。<model-viewer>

在 ar-modes 中使用 scene-viewer 模式時，系統會切換至原生 AR 檢視畫面，並邀請使用者透過 Scene Viewer 將模型放置在環境中。

如果沒有 Google Play 服務 (AR)，輕觸這個按鈕會以 <model-viewer> 的 3D 檢視器顯示模型。

請參閱 <model-viewer> 說明文件，進一步瞭解如何開始使用 <model-viewer>。

模型檔案規定

Scene Viewer 對模型有以下支援和限制。

支援的檔案格式 glTF 2.0/glb，並使用下列擴充功能：
  • KHR_materials_unlit
  • KHR_texture_transform
動畫
  • 循環播放骨架動畫
  • 循環播放的剛體動畫
  • 循環播放的變形動畫
動畫會循環播放。如果 glTF 檔案包含多個動畫，Scene Viewer 只會播放第一個動畫。
建議限值 素材資源的整體效能取決於設定限制，以及在頂點、材質、紋理解析度、每個材質的網格和其他因素之間進行取捨。請按照下列規範，對素材資源進行最佳化。
  • 三角形數量：建議上限為 100,000 個三角形，但如要維持 Scene Viewer 的高效能，請盡量減少三角形數量。理想範圍為 30,000 到 50,000。
  • 材質數量：建議上限為 10 個材質，其中兩個可為 Alpha 材質。盡可能設定最低數量，確保素材資源維持良好成效。
  • 每個材質的網格：1
  • 紋理解析度上限：2048 × 2048
  • 骨骼 (包括未加權重的關節點)：254 (硬性限制)
  • 每個頂點的骨骼權重限制：4 (嚴格限制)
  • UV：每個網格 1 個 UV (嚴格限制)
  • 模型大小：10 MB (模型越大，使用者體驗可能越差)。
Shadow 支援 放置物件時，Scene Viewer 會自動算繪硬陰影，因此建議不要將陰影烘焙到模型中。
支援材質
  • PNG 格式：PNG-24、已建立索引的 PNG-8。
    如果沒有透明度，建議使用 JPG，因為可縮減大小。
  • 色域：sRGB
材質 PBR
載入檔案 HTTPS
Scene
  • 軸：右側，具有下列屬性：
    • +X 是正確的
    • +Y 軸向上
    • -Z 點從原點向前移動 (換句話說，資產的「正面」應朝向 +Z)
  • 比例：1 個單位 = 1 公尺 (如 glTF 規格所定義，確保模型以真實比例置於 AR 中)

使用預覽工具驗證 3D 模型

如要確保 3D 模型檔案能在 Scene Viewer 中正常顯示，請使用線上預覽工具驗證電腦上的檔案。

驗證 3D 模型

如要驗證模型，預覽工具需要一個 glb 或 glTF 檔案、任何相關聯的圖片和 bin 檔案，以及選用的音訊檔案。音訊檔案會與動畫 0 一起循環播放。

你可以選取多個檔案，也可以選擇將 glb 或 glTF 檔案及其相關聯的檔案放入 zip 檔案。(ZIP 檔案方法不支援音訊檔案)。

如要驗證 3D 模型，請按照下列步驟操作：

  1. 在瀏覽器中開啟線上預覽工具。

  2. 請使用下列其中一種方式，將檔案新增至預覽工具：

    • 拖曳。選取 glb 或 glTF 檔案和所有相關聯的檔案 (或包含這些檔案的 zip 檔案)，然後將選取的檔案或 zip 檔案拖曳至預覽工具。

    • 透過預覽工具。在預覽工具中，依序選擇「Scene Viewer」>「Load File」。選取 glb 或 glTF 檔案和所有相關聯的檔案 (或含有這些檔案的 ZIP 檔案)，然後按一下「開啟」。

將包含 3D 模型的檔案載入預覽工具後，瀏覽器底部的控制台會顯示結果，包括任何錯誤訊息。

新增 3D 模型以進行驗證

如要驗證 3D 模型，請將組成 3D 模型的檔案新增至模型編輯器工具。

如要驗證模型，預覽工具需要模型的 glb 或 glTF 檔案、任何相關聯的圖片和 bin 檔案，以及選用的音訊檔案。你可以選取多個檔案，也可以新增單一 ZIP 檔案。

新增 zip 檔案時，預覽器會載入找到的第一個 glb 或 glTF，以及該 zip 檔案中的相關聯圖片和 bin 檔案。

  1. 在瀏覽器中開啟模型編輯器工具。

  2. 請使用下列其中一種方式，將檔案新增至預覽工具：

    • 如要拖曳檔案進行驗證，請選取 glb 或 glTF 檔案和任何相關聯的檔案 (或選取包含這些檔案的 zip 檔案)，然後拖曳至預覽工具。

    • 從預覽工具選取檔案。在預覽工具中，依序選擇「Scene Viewer」>「Load File」。多選 glb 或 glTF 檔案，以及所有相關聯的檔案 (或包含這些檔案的 zip 檔案)，然後按一下「開啟」。

驗證錯誤

錯誤代碼 嚴重性 訊息 目前支援的值
INVALID_INPUT_FILE_EXTENSION 錯誤 驗證工具不支援輸入檔案「[filename]」的副檔名。 ['.glb', '.gltf']
REC_INPUT_BINARY_SIZE_EXCEEDED 警告 提供的使用者輸入內容二進位檔大小超過 Scene Viewer 規格建議的限制 ([size] MB)。 10
MAX_INPUT_BINARY_SIZE_EXCEEDED 錯誤 提供的使用者輸入內容二進位檔大小超過 Scene Viewer 規格支援的上限 ([size] MB)。 15
UNSUPPORTED_GLTF_EXTENSION_USED 錯誤 Scene Viewer 規格不支援 glTF 中的延伸模組 [ext]。 ['KHR_materials_pbrSpecularGlossiness', 'KHR_materials_unlit', 'KHR_texture_transform']
ANIMATION_LIMIT_EXCEEDED 錯誤 glTF 中的動畫數超過 Scene Viewer 規格支援的限制，上限為 [num] 個動畫。 1
MORPH_TARGET_USED 錯誤 glTF 包含 Scene Viewer 規格不支援的變形目標。
MATERIAL_LIMIT_EXCEEDED 警告 glTF 中的材質數超過 Scene Viewer 規格建議的限制，上限為 [num] 個材質。 10
TEXTURE_RESOLUTION_LIMIT_EXCEEDED 警告 glTF 中位於索引 [idx] 的圖片解析度超過 Scene Viewer 規格建議的限制，解析度上限為 [res] x [res]。 2048 x 2048
UV_LIMIT_EXCEEDED 錯誤 glTF 中的每一網狀 UV 數超過 Scene Viewer 規格支援的限制，上限為每個網狀 [num] 個 UV。 1
VERTEX_COLOR_USED 錯誤 glTF 包含 Scene Viewer 規格不支援的頂點色彩。
JOINT_LIMIT_EXCEEDED 錯誤 glTF 中的節點數超過 Scene Viewer 規格支援的限制，上限為 [num] 個節點。 254
TRIANGLE_LIMIT_EXCEEDED 警告 glTF 中的三角形數超過 Scene Viewer 規格建議的限制，上限為 [num] 個三角形。 100,000
PRIMITIVE_MODE_UNSUPPORTED 錯誤 Scene Viewer 規格不支援基元模式「[mode]」。 {4 : Triangle List, 5 : Triangle Strip, 6 : Triangle Fan}
MISSING_PBR_METALLIC_ROUGHNESS 資訊 位於索引 [idx] 的材質缺少 pbrMetallicRoughness 屬性。如果使用的是金屬和粗糙度因數，Scene Viewer 規格就不一定要有這個屬性。如未使用這兩種因數，該材質會使用預設值，但這可能會引發預料外的行為。