啟用 Azure 監視器 Application Insights 實際使用者監視

發行項
03/28/2024

Microsoft Azure 監視器 Application Insights JavaScript SDK 會收集使用量資料，以便您監視和分析 JavaScript Web 應用程式的效能。這通常稱為「實際使用者監視」(RUM)。

Application Insights JavaScript SDK 具有基本 SDK 和數個外掛程式，可提供更多功能。

我們預設會收集頁面檢視。不過，如果您想要預設也收集點選，請考慮新增 Click Analytics 自動收集外掛程式：

如果您要新增架構延伸模組，您可以在遵循下列步驟開始後新增此延伸模組，您可以在新增架構延伸模組時選擇新增 Click Analytics。
如果您未新增架構延伸模組，請在遵循步驟開始之後新增 Click Analytics 外掛程式。

我們提供偵錯外掛程式和效能外掛程式進行偵錯/測試。在極少數情況下，您可以新增自訂外掛程式建置自己的延伸模組。

必要條件

Azure 訂用帳戶：免費建立 Azure 訂用帳戶
Application Insights 資源：建立 Application Insights 資源
使用 JavaScript 的應用程式

開始使用

請遵循本節中的步驟，使用 Application Insights JavaScript SDK 檢測您的應用程式。

提示

好消息！我們可讓您更輕鬆地啟用 JavaScript。查看哪裡可取得 JavaScript (Web) SDK 載入器指令碼根據設定插入！

新增 JavaScript 程式碼

有兩種方法可用來新增程式碼，透過 Application Insights JavaScript SDK 啟用 Application Insights：

方法	我何時會使用此方法？
JavaScript (Web) SDK 載入器指令碼	對於大多數客戶，我們建議使用 JavaScript (Web) SDK 載入器指令碼，因為您永遠不需要更新 SDK，而且會自動取得最新的更新。此外，您也可以控制要新增 Application Insights JavaScript SDK 的頁面。
NPM 套件	您想要將 SDK 帶入您的程式碼，並啟用 IntelliSense。只有需要更多自訂事件和設定的開發人員才需要此選項。如果您打算使用 React、React Native 或 Angular 架構延伸模組，則需要此方法。

JavaScript (Web) SDK 載入器指令碼
NPM 套件

在您想要啟用 Application Insights 的每個頁面頂端貼上 JavaScript (Web) SDK 載入器指令碼。

最好新增該指令碼成為 <head> 區段中的第一個指令碼，以便監視全部相依性的任何潛在問題。

如果偵測到 Internet Explorer 8，則會自動載入 JavaScript SDK v2.x。

<script type="text/javascript">
!(function (cfg){function e(){cfg.onInit&&cfg.onInit(i)}var S,u,D,t,n,i,C=window,x=document,w=C.location,I="script",b="ingestionendpoint",E="disableExceptionTracking",A="ai.device.";"instrumentationKey"[S="toLowerCase"](),u="crossOrigin",D="POST",t="appInsightsSDK",n=cfg.name||"appInsights",(cfg.name||C[t])&&(C[t]=n),i=C[n]||function(l){var d=!1,g=!1,f={initialize:!0,queue:[],sv:"7",version:2,config:l};function m(e,t){var n={},i="Browser";function a(e){e=""+e;return 1===e.length?"0"+e:e}return n[A+"id"]=i[S](),n[A+"type"]=i,n["ai.operation.name"]=w&&w.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(f.sv||f.version),{time:(i=new Date).getUTCFullYear()+"-"+a(1+i.getUTCMonth())+"-"+a(i.getUTCDate())+"T"+a(i.getUTCHours())+":"+a(i.getUTCMinutes())+":"+a(i.getUTCSeconds())+"."+(i.getUTCMilliseconds()/1e3).toFixed(3).slice(2,5)+"Z",iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}},ver:4,seq:"1",aiDataContract:undefined}}var h=-1,v=0,y=["js.monitor.azure.com","js.cdn.applicationinsights.io","js.cdn.monitor.azure.com","js0.cdn.applicationinsights.io","js0.cdn.monitor.azure.com","js2.cdn.applicationinsights.io","js2.cdn.monitor.azure.com","az416426.vo.msecnd.net"],k=l.url||cfg.src;if(k){if((n=navigator)&&(~(n=(n.userAgent||"").toLowerCase()).indexOf("msie")||~n.indexOf("trident/"))&&~k.indexOf("ai.3")&&(k=k.replace(/(\/)(ai\.3\.)([^\d]*)$/,function(e,t,n){return t+"ai.2"+n})),!1!==cfg.cr)for(var e=0;e<y.length;e++)if(0<k.indexOf(y[e])){h=e;break}var i=function(e){var a,t,n,i,o,r,s,c,p,u;f.queue=[],g||(0<=h&&v+1<y.length?(a=(h+v+1)%y.length,T(k.replace(/^(.*\/\/)([\w\.]*)(\/.*)$/,function(e,t,n,i){return t+y[a]+i})),v+=1):(d=g=!0,o=k,c=(p=function(){var e,t={},n=l.connectionString;if(n)for(var i=n.split(";"),a=0;a<i.length;a++){var o=i[a].split("=");2===o.length&&(t[o[0][S]()]=o[1])}return t[b]||(e=(n=t.endpointsuffix)?t.location:null,t[b]="https://"+(e?e+".":"")+"dc."+(n||"services.visualstudio.com")),t}()).instrumentationkey||l.instrumentationKey||"",p=(p=p[b])?p+"/v2/track":l.endpointUrl,(u=[]).push((t="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",n=o,r=p,(s=(i=m(c,"Exception")).data).baseType="ExceptionData",s.baseData.exceptions=[{typeName:"SDKLoadFailed",message:t.replace(/\./g,"-"),hasFullStack:!1,stack:t+"\nSnippet failed to load ["+n+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(w&&w.pathname||"_unknown_")+"\nEndpoint: "+r,parsedStack:[]}],i)),u.push((s=o,t=p,(r=(n=m(c,"Message")).data).baseType="MessageData",(i=r.baseData).message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+s+")").replace(/\"/g,"")+'"',i.properties={endpoint:t},n)),o=u,c=p,JSON&&((r=C.fetch)&&!cfg.useXhr?r(c,{method:D,body:JSON.stringify(o),mode:"cors"}):XMLHttpRequest&&((s=new XMLHttpRequest).open(D,c),s.setRequestHeader("Content-type","application/json"),s.send(JSON.stringify(o))))))},a=function(e,t){g||setTimeout(function(){!t&&f.core||i()},500),d=!1},T=function(e){var n=x.createElement(I),e=(n.src=e,cfg[u]);return!e&&""!==e||"undefined"==n[u]||(n[u]=e),n.onload=a,n.onerror=i,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||a(0,t)},cfg.ld&&cfg.ld<0?x.getElementsByTagName("head")[0].appendChild(n):setTimeout(function(){x.getElementsByTagName(I)[0].parentNode.appendChild(n)},cfg.ld||0),n};T(k)}try{f.cookie=x.cookie}catch(p){}function t(e){for(;e.length;)!function(t){f[t]=function(){var e=arguments;d||f.queue.push(function(){f[t].apply(f,e)})}}(e.pop())}var r,s,n="track",o="TrackPage",c="TrackEvent",n=(t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+o,"stop"+o,"start"+c,"stop"+c,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),f.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4},(l.extensionConfig||{}).ApplicationInsightsAnalytics||{});return!0!==l[E]&&!0!==n[E]&&(t(["_"+(r="onerror")]),s=C[r],C[r]=function(e,t,n,i,a){var o=s&&s(e,t,n,i,a);return!0!==o&&f["_"+r]({message:e,url:t,lineNumber:n,columnNumber:i,error:a,evt:C.event}),o},l.autoExceptionInstrumented=!0),f}(cfg.cfg),(C[n]=i).queue&&0===i.queue.length?(i.queue.push(e),i.trackPageView({})):e();})({
src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
// name: "appInsights",
// ld: 0,
// useXhr: 1,
crossOrigin: "anonymous",
// onInit: null,
// cr: 0,
cfg: { // Application Insights Configuration
 connectionString: "YOUR_CONNECTION_STRING"
}});
</script>

(選擇性) 視您需要最佳化網頁載入或解決載入錯誤而定，新增或更新選用的 JavaScript (Web) SDK 載入器指令碼設定。

JavaScript (Web) SDK 載入器指令碼設定

名稱	類型	是必要的嗎？	描述
src	string	必要	要從何處載入 SDK 的完整 URL。此值用於動態新增 <script /> 標記的 "src" 屬性。您可以使用公用 CDN 位置或您自己私人裝載的位置。
NAME	字串	選擇性	已初始化 SDK 的全域名稱。如果您需要同時初始化兩個不同的 SDK，請使用此設定。預設值為 appInsights，因此 `window.appInsights` 是初始化執行個體的參考。注意：如果您指派名稱值，或先前的執行個體已指派給全域名稱 appInsightsSDK，SDK 初始化程式碼會要求該值在全域命名空間中成為 `window.appInsightsSDK=<name value>`，藉以確保正確的 JavaScript (Web) SDK 載入器指令碼基本架構，並初始化和更新 Proxy 方法。
識別碼	毫秒數	選擇性	定義要在嘗試載入 SDK 之前等候的載入延遲。 HTML 頁面無法載入時，請使用此設定，因為 JavaScript (Web) SDK 載入器指令碼在錯誤的時間載入。預設值為逾時後 0 毫秒。如果您使用負值，指令碼標記會立即新增至頁面的 `<head>` 區域，並封鎖頁面載入事件，直到指令碼載入或失敗為止。
useXhr	boolean	選擇性	此設定僅用於報告 SDK 載入失敗。例如，JavaScript (Web) SDK 載入器指令碼阻止 HTML 頁面載入時，此設定很有用，導致 fetch() 無法使用。如果可行，報告會先嘗試使用 fetch()，然後再後援至 XHR。將此設定設為 `true` 略過擷取檢查。只有在您的應用程式在擷取無法傳送失敗事件的環境中，例如 JavaScript (Web) SDK 載入器指令碼未成功載入時，才需要此設定。
crossOrigin	string	選擇性	包括此設定，新增以下載 SDK 的指令碼標記將會包括具有此字串值的 crossOrigin 屬性。您需要提供 CORS 的支援時，請使用此設定。未定義時 (預設值)，不會新增 crossOrigin 屬性。未定義建議的值 (預設值)、"" 或 "anonymous"。關於全部有效值，請參閱跨原始來源 HTML 屬性文件。
onInit	function(aiSdk) { ... }	選擇性	在成功從 CDN 載入並初始化主要 SDK 指令碼之後，會呼叫此回撥函式 (根據 src 值)。您需要插入遙測初始設定式時，此回撥函式很有用。這會傳遞一個引數，針對所呼叫的 SDK 執行個體參考，也會在第一個初始頁面檢視之前呼叫。如果 SDK 已載入並初始化，仍會呼叫此回撥。注意：在處理 sdk.queue 陣列期間，會呼叫此回撥。您無法再將任何項目新增至佇列，因為會忽略和卸除這些項目。 (新增為 JavaScript (Web) SDK 載入器指令碼第 5 版--指令碼中的 sv:"5" 值)。
cr	boolean	選擇性	如果 SDK 無法載入，而且對於 `src` 定義的端點值是公用 CDN 位置，此設定選項會嘗試立即從下列其中一個備份 CDN 端點載入 SDK： js.monitor.azure.com js.cdn.applicationinsights.io js.cdn.monitor.azure.com js0.cdn.applicationinsights.io js0.cdn.monitor.azure.com js2.cdn.applicationinsights.io js2.cdn.monitor.azure.com az416426.vo.msecnd.net 注意：部分支援 az416426.vo.msecnd.net，因此不建議這麼做。如果 SDK 已成功從備份 CDN 端點載入，這會從伺服器執行成功的負載檢查時決定的第一個可用端點載入。如果 SDK 無法從任何備份 CDN 端點載入，SDK 失敗錯誤訊息隨即出現。未定義時，預設值為 `true`。如果您不想從備份 CDN 端點載入 SDK，請將此設定選項設定為 `false`。如果您要從您自己的私人裝載的 CDN 端點載入 SDK，則不適用此設定選項。

使用下列命令來安裝 Microsoft Application Insights JavaScript SDK - Web 套件。
```
npm i --save @microsoft/applicationinsights-web
```
「此套件隨附 typings」，因此您「不」需要安裝個別的 typings 套件。

將下列 JavaScript 新增至應用程式的程式碼。

新增此 JavaScript 程式碼的位置和方式取決於應用程式的程式碼。例如，您可以完全如下面所示新增，或者您可能需要建立包裝函式。

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
  connectionString: 'YOUR_CONNECTION_STRING'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView();

在您的環境中貼上連接字串

若要在您的環境中貼上連接字串，請遵循下列步驟：

瀏覽至 Application Insights 資源的 [概觀] 窗格。
找到連線字串。
選取 [複製到剪貼簿] 圖示將連接字串複製到剪貼簿。
將 JavaScript 程式碼中的預留位置 "YOUR_CONNECTION_STRING" 取代為複製到剪貼簿的連接字串。

connectionString 格式必須遵循「InstrumentationKey=xxxx;....」。如果提供的字串不符合此格式，SDK 載入流程就會失敗。

連接字串不會被視為安全性權杖或金鑰。如需詳細資訊，請參閱新的 Azure 區域是否需要使用連接字串？。

(選擇性) 新增 SDK 設定

選用的 SDK 設定會在初始化期間傳遞至 Application Insights JavaScript SDK 的設定。

若要新增 SDK 設定，請直接在 connectionString 下新增每個設定選項。例如：

(選擇性) 新增進階 SDK 設定

如果您要針對特定架構使用外掛程式所提供的額外功能，並選擇啟用 Click Analytics 外掛程式，請參閱：

確認資料正在流動

移至您已啟用 SDK 的 Application Insights 資源。
在左側的 Application Insights 資源功能表中，選取 [調查] 下的 [交易搜尋] 窗格。
開啟 [事件類型] 下拉式功能表，並且勾選 [全選] 取消勾選功能表中的核取方塊。
從 [事件類型] 下拉式功能表中，選取：
- Azure 監視器 Application Insights 實際使用者監視的頁面檢視
- Click Analytics 自動收集外掛程式的自訂事件。
資料可能需要幾分鐘的時間才會顯示在入口網站中。如果您看到的唯一資料是載入失敗例外狀況，請參閱針對 JavaScript Web 應用程式的 SDK 載入失敗進行疑難排解。

在某些情況下，如果多個不同版本的 Application Insights 執行個體在同一個頁面上執行，則初始化期間可能會發生錯誤。如需這些案例和出現的錯誤訊息，請參閱在一個工作階段中執行多個版本的 Application Insights JavaScript SDK。如果您遇到其中一個錯誤，請嘗試使用 name 設定來變更命名空間。如需詳細資訊，請參閱 JavaScript (Web) SDK 載入器指令碼設定。
如果您要查詢資料以確認資料正在流動：
1. 選取左窗格中的 [記錄]。
  
  您選取 [記錄] 時，[查詢] 對話方塊隨即開啟，其中包含與您的資料相關的範例查詢。
2. 針對您想要執行的範例查詢，選取 [執行]。
3. 如有需要，您可以使用 Kusto 查詢語言 (KQL) 更新範例查詢或撰寫新的查詢。
  
  如需基本的 KQL 運算子，請參閱了解常見的 KQL 運算子。

常見問題集

本節提供常見問題的答案。

什麼是使用者和和工作階段計數？

JavaScript SDK 會在 Web 用戶端上設定使用者 Cookie 來識別傳回使用者，以及設定一個工作階段 Cookie 來將活動分組。
如果沒有任何用戶端指令碼，則您可以在伺服器設定 Cookie。
如果有一個真實的使用者以不同的瀏覽器使用您的站台，或是使用 in-private/Incognito 瀏覽，或透過不同的電腦，則系統會將其計算多次。
若要跨電腦和瀏覽器識別登入的使用者，請新增對 setAuthenticatedUserContext() 的呼叫。

什麼是 JavaScript SDK 效能/額外負荷？

Application Insights JavaScript SDK 在您的網站上擁有最少的額外負荷。如果剛好 36 KB gzipped，而且只需要大約 15 毫秒即可初始化，則 SDK 會將可忽略的載入時間量新增至您的網站。您使用 SDK 時，程式庫的最小元件會快速載入，並在背景下載完整的指令碼。

此外，指令碼從 CDN 下載時，您頁面的全部追蹤都會排入佇列，因此您不會在頁面的整個生命週期內遺失任何遙測。此設定程序會為您的頁面提供順暢、使用者看不到的分析系統。

JavaScript SDK 支援哪些瀏覽器？


Chrome 最新版本 ✔	Firefox 最新版本 ✔	v3.x: IE 9+ 和 Microsoft Edge ✔ v2.x: IE 8+ 相容和 Microsoft Edge ✔	Opera 最新版本 ✔	Safari 最新版本 ✔