[Alpha]{class="badge informative"}
Server SDK for JavaScript overview
The Adobe Experience Platform Server SDK for JavaScript, or Server SDK, is a library that runs on your server and sends data to the Adobe Experience Platform Edge Network. It runs in Node.js and in other server-side JavaScript runtimes that meet its requirements. It is published to npm as @adobe/alloy-node. This guide covers its core concepts, installation, configuration, and methods.
The Server SDK shares its core with the Web SDK. It uses the same datastreams, the same XDM data model, and the same identity and consent cookies. Because it runs on a server instead of in a browser, it differs in how you create instances, authenticate, and handle each visitor’s request.
When to use the Server SDK when-to-use
Adobe offers several ways to send data to the Edge Network. Choose the one that matches where your code runs:
You can use the Server SDK and the Web SDK together. For example, your server can request personalized content, and the browser can render it. See Hybrid personalization.
How it works how-it-works
- When your server starts, you create one instance and call
configureonce with your datastream, organization, and API credentials. - For each incoming request, you call
forRequestto get a handle that is scoped to that visitor. The handle reads and writes the visitor’s identity and consent through the cookie service that you provide, and forwards the visitor’s request headers (such asUser-Agent) to the Edge Network. - You call methods on the handle, such as
sendEvent. The SDK sends events to the authenticated Edge Network Server API using an access token that it obtains and caches for you. - The SDK returns the results to your code. For example,
sendEventreturns personalization propositions as data. The SDK does not render them. Your application decides what to do with them, such as including them in the page for the Web SDK to render.
See Instances and requests for more details.
Supported features features
The following table lists what the alpha release supports. See Differences from Web SDK for a detailed comparison.
sendEventgetIdentity and appendIdentityToUrlsetConsent and defaultConsentdefaultConsent accepts only "in" and "out".personalizationdebugEnabled and setDebugRequirements requirements
Before you use the Server SDK, make sure that you have the following:
- A server-side JavaScript runtime, such as Node.js 22 or later. The runtime must support ECMAScript modules, because you load the package with
import. It must also provide the following web-standard globals:fetch,Headers,URLSearchParams,crypto.getRandomValues,setTimeout,clearTimeout,atob,btoa,TextEncoder,TextDecoder, andconsole. See Runtime support. - A datastream. See Configure a datastream. If you use
getIdentity,appendIdentityToUrl, orsetConsent, set the datastream’s Access Type to Mixed Authentication, because these methods send unauthenticated requests. See Authentication. - An OAuth Server-to-Server credential from the Adobe Developer Console. The SDK requires it and uses it to authenticate the events that it sends. See Authentication.
- An XDM schema and dataset, if you send data to Adobe Experience Platform.
Runtime support runtime-support
The Server SDK is supported in any server-side JavaScript runtime that meets the requirements. It doesn’t depend on Node.js-specific modules. Its default platform services use only web-standard APIs, such as fetch.
These guides use Node.js as the primary example runtime. Code examples use Node.js conventions, such as reading credentials from process.env and handling requests with the node:http module. If you use a different runtime, replace these parts with your runtime’s equivalents. The SDK’s own methods work the same way in every supported runtime.
Source code and feedback source
The Server SDK is open source. Its source code is in the packages/node folder of the adobe/alloy repository on GitHub. Report issues and request features in that repository.