PINGWorks.SitecoreCDP.GuestSDK 1.1.0

PINGWorks.SitecoreCDP.GuestSDK

This is a .NET SDK for working with Sitecore CDP's Guest API.<br /> More information about Sitecore's API is at Guest API Doc (official)

Features

• Typed, DI-friendly service for interacting with the Sitecore CDP Guest API v2.1
• Async-first API with CancellationToken support and full XML documentation comments
• NetStandard 2.1 for wide compatibility
• HTTP Basic Auth using Client Key and API Token from the CDP portal
• Focused sub-interfaces for guest management and data extensions

Getting started

Prerequisites

To work with the SDK you will need a Client Key and API Token from Settings > API access in the Sitecore CDP portal.

Install

From your project directory:

dotnet add package PINGWorks.SitecoreCDP.GuestSDK

AppSettings

Properties are available to configure the SDK through configuration binding. The snippet below shows all options along with their default values.

{
    /* The Sitecore CDP API region. Valid values: US, EU, AP, JP (default: US) */
    "Region": "US",

    /* The Client Key from Settings > API access in the Sitecore CDP portal */
    "ClientKey": "[Your Client Key]",

    /* The API Token from Settings > API access in the Sitecore CDP portal */
    "ApiToken": "[Your API Token]"
}

The regional endpoint URLs default to the standard Sitecore values. If you need to override a specific region's URL, set the corresponding property (ServiceEndpointUs, ServiceEndpointEu, ServiceEndpointAp, or ServiceEndpointJp).

We recommend the use of Visual Studio's User Secrets feature to store sensitive information such as ClientKey and ApiToken during development.

Register services

Register the SDK in Program.cs, e.g. when using the minimal hosting model:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Register SDK services - set options through binding or manually
builder.Services.AddSitecoreCdpGuestSDK( opt => config.GetSection( "mySettings" ).Bind( opt ) );

HttpClient defaults. This call (via AddSitecoreEECommon) applies AddStandardResilienceHandler() and a DEBUG-only console request/response logger to every HttpClient in your container — not just the SDK's own. See the PINGWorks.SitecoreExperienceEdge.Common README for how to customize the resilience options per-client.

This library uses Json serialization through System.Text.Json.

Guest type and status values

Use the enum and string constant types for type-safe API values:

using PINGWorks.SitecoreCDP.GuestSDK.Enums;

var request = new CreateGuestRequest
{
    GuestType = GuestType.Customer,
    FirstName = "Jane",
    LastName = "Smith",
    Subscriptions =
    [
        new GuestSubscription
        {
            Channel = "EMAIL",
            Name = "newsletter",
            PointOfSale = "my-store",
            Status = SubscriptionStatus.Subscribed
        }
    ]
};

Data extensions

Each guest can have up to six free-form key-value data extension slots. Use DataExtensionName enum values for the slot name:

using PINGWorks.SitecoreCDP.GuestSDK.Enums;

var ext = await sdk.CreateGuestDataExtension( guestRef, new CreateGuestDataExtensionRequest
{
    Name = DataExtensionName.Ext1,
    AdditionalData = new Dictionary<string, object>
    {
        ["vipMember"] = true,
        ["loyaltyTier"] = "gold",
        ["points"] = 1500
    }
});

Available services

Guests — ISitecoreCdpGuestSdk

Guest data extensions — ISitecoreCdpGuestExtensionsSdk