[Alpha]{class="badge informative"}

安裝伺服器SDK

最後更新： 2026年11月6日

主題：
伺服器 API

建立對象：

中繼
開發人員

伺服器SDK可在npm上當作@adobe/alloy-node套件使用。使用npm或您的執行階段使用的套件管理員將其安裝在您的伺服器專案中：

npm install @adobe/alloy-node

套件會以ECMAScript模組形式發佈，並在任何符合需求的伺服器端JavaScript執行階段中執行。使用import載入它：

import { createInstance } from "@adobe/alloy-node";

NOTE

本指南中的範例使用Node.js。如果您使用不同的執行階段，請將Node.js特定程式碼（例如process.env和node:http模組）取代為您執行階段的同等程式碼。請參閱執行階段支援。

建立執行個體 create-instance

createInstance函式傳回SDK的執行個體，其中包含所有可用的選用元件（同意和Personalization）。大部分實施都使用此函式。

import { createInstance } from "@adobe/alloy-node";

const alloy = createInstance({ name: "alloy" });

createInstance函式接受具有下列屬性的選用物件：

屬性

類型

說明

name

字串

SDK新增至其記錄訊息的前置詞，例如[alloy]。預設為"alloy"。如果您在相同處理序中執行多個執行個體，且想將其記錄分開，請設定不同的名稱。

monitors

陣列

監視掛接物件的陣列。每個物件都可以包含SDK在執行時呼叫的函式，例如onInstanceCreated、onInstanceConfigured和onBeforeCommand。這些掛接的運作方式與Web SDK監視掛接相同。

platformServices

物件

取代SDK用於網路、儲存和Cookie的一或多個內建服務。大部分實施不需要此屬性。請參閱平台服務。

傳回的執行個體會公開方法，例如configure、forRequest和sendEvent。與Web SDK不同，您可以直接在執行個體上呼叫方法，例如alloy.sendEvent({ ... })，而不是以字串形式傳遞命令名稱。

建立自訂執行個體 custom-instance

如果您不需要每個選用元件，請使用createCustomInstance並只傳遞您想要的元件。 components匯出包含每個選用元件：

元件

新增

components.consent

setConsent方法和defaultConsent組態選項。

components.personalization

能夠使用sendEvent的personalization選項要求個人化。

import { createCustomInstance, components } from "@adobe/alloy-node";

// Includes consent, but not personalization
const alloy = createCustomInstance({
  components: [components.consent]
});

前後關聯、資料收集、身分和物件庫資訊元件一律包含在內。若您省略選用元件：

元件提供的方法仍存在於例項上，但呼叫時會拒絕這些方法。例如，setConsent會以訊息包含The setConsent command does not exist的錯誤拒絕。
configure已拒絕元件提供的組態選項。例如，defaultConsent導致configure拒絕，並產生Unknown field錯誤。
元件在其他方法中讀取的選項會被忽略。例如，即使您設定personalization選項，sendEvent也不會要求個人化。

createCustomInstance接受相同的name、monitors和platformServices屬性做為createInstance。

傳送測試事件 test-event

設定驗證之後，您可以設定執行個體並傳送一個事件，以確認安裝是否正常運作。將您的憑證儲存在環境變數中，而非原始程式碼中。

import { createInstance } from "@adobe/alloy-node";

const alloy = createInstance();

await alloy.configure({
  datastreamId: "ebebf826-a01f-4458-8cec-ef61de241c93",
  orgId: "ADB3LETTERSANDNUMBERS@AdobeOrg",
  edgeCredentials: {
    clientId: process.env.ADOBE_CLIENT_ID,
    clientSecret: process.env.ADOBE_CLIENT_SECRET,
    scopes: process.env.ADOBE_SCOPES.split(",")
  }
});

const result = await alloy.sendEvent({
  xdm: {
    eventType: "web.webpagedetails.pageViews",
    identityMap: {
      Email: [{ id: "test-visitor@example.com", primary: true }]
    }
  }
});

console.log("Event sent", result);

如果事件成功，Promise就會解析。如果失敗，Promise會以描述問題的錯誤拒絕，例如無效認證或缺少主要身分。將debugEnabled設為true以將每個步驟記錄到主控台。

IMPORTANT

此測試會從頂層執行個體傳送事件，在流程的整個生命週期中保留單一身分。在您的應用程式中，改為呼叫每個訪客請求的forRequest控制代碼上的方法。請參閱執行個體和要求。

後續步驟 next-steps

recommendation-more-help

experience-platform-help-collection