Opti.ODP 1.0.2-beta

Opti.ODP

Optimizely Data Platform (ODP) integration for Optimizely CMS 12. Provides visitor group criteria based on real-time ODP audiences with scheduled audience caching, encrypted cookie-based tracking, and a diagnostic API.

Features

• Visitor Group Criterion — Select ODP audiences from a dropdown in the CMS admin UI
• Scheduled Audience Sync — Automatically caches all ODP audiences every hour via a scheduled job
• Real-time Audience Matching — Fetches user audience membership from ODP on every page load via middleware
• Encrypted Cookie Tracking — Stores matched audiences in an encrypted usr_seg cookie (configurable)
• Resilient Caching — Cache persists for 24 hours and is preserved if the sync job fails
• Load-balanced Support — Uses ISynchronizedObjectInstanceCache for multi-server environments
• Fallback — Criterion reads from cookie first; if missing, fetches from ODP API and sets the cookie

Installation

1. Install NuGet Package

dotnet add package Opti.ODP

Or via Package Manager Console: Install-Package Opti.ODP

2. Configure in Startup.cs

public void ConfigureServices(IServiceCollection services) { // Register ODP services (before AddCms) services.AddOptimizelyOdp(Configuration); services.AddCms(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { app.UseAuthentication(); app.UseAuthorization(); // ODP middleware — fetches user audiences on every page load app.UseMiddleware<Optimizely.ODP.Middleware.OdpSegmentMiddleware>();

app.UseRouting(); app.UseEndpoints(endpoints ⇒ { endpoints.MapControllers(); endpoints.MapContent(); }); }

3. Add Configuration (appsettings.json)

{ "Optimizely": { "OdpSettings": { "PrivateApiKey": "your-private-api-key-here", "ApiHost": "https://api.zaius.com", "SegmentCookieName": "usr_seg", "SegmentCookieExpirationMinutes": 10, "SegmentCacheExpirationMinutes": 1440, "EncryptCookie": true } } }

Where to find your API key:

1. Log in to your ODP account
2. Navigate to Settings → APIs & Credentials
3. Copy your Private API Key

4. Run the Audience Sync Job

1. Go to Admin → Scheduled Jobs
2. Find ODP Audience Sync
3. Click Start Manually to populate the cache for the first time
4. The job runs automatically every hour (configurable in Admin UI)

5. Restart Your Application

After installation and configuration, restart your application.

How It Works

Page Load │ ├─ Middleware (runs first on every page load) │ ├─ Reads vuid cookie │ ├─ Parses GUID (removes hyphens and timestamp) │ ├─ Calls ODP GraphQL API with cached audience subset │ └─ Writes/refreshes encrypted usr_seg cookie │ ├─ Visitor Group Criterion (runs during page render) │ ├─ Reads usr_seg cookie (fast, no API call) │ ├─ Decrypts and checks audience membership │ └─ If cookie missing → falls back to ODP API call │ └─ Response sent with fresh usr_seg cookie

Usage

Creating Visitor Groups

1. In Optimizely CMS, go to Admin → Visitor Groups
2. Create a new visitor group or edit an existing one
3. Click Add Criterion
4. Select Optimizely ODP → ODP Audience
5. Choose an ODP audience from the dropdown
6. Save the visitor group

Programmatic Usage

public class MyController : Controller { private readonly IOdpService _odpService; public MyController(IOdpService odpService) { _odpService = odpService; }

public async Task<IActionResult> Index() { var userId = Request.Cookies["vuid"] ?? User.Identity?.Name;

// Get all matched audiences for a user (calls ODP API)
var audiences = await _odpService.GetCustomerSegmentsAsync(userId);

// Check if user is in a specific audience
var isVip = await _odpService.IsInSegmentAsync(userId, "VIP Customers");

// Read audiences from cookie only (no API call)
var cookieAudiences = _odpService.GetAudiencesFromCookie(HttpContext);

// Get customer fields
var fields = await _odpService.GetCustomerFieldsAsync(userId, new[] { "email", "loyalty_tier" });

// Post an event to ODP
await _odpService.PostEventAsync("page_view", "viewed", new Dictionary<string, object>
{
    ["page_name"] = "Home",
    ["category"] = "Landing"
});

return View();

} }

Configuration Options

Cookie Encryption

When EncryptCookie is true (default), the usr_seg cookie value is encrypted using ASP.NET Data Protection (AES-256).

The package handles both formats seamlessly. You can switch between encrypted and plain at any time without losing existing cookies.

Scheduled Job

The job output displays all synced audience names as a comma-separated list.

API Reference

IOdpService

Troubleshooting

Dropdown shows no audiences

1. Run the ODP Audience Sync job manually from Admin → Scheduled Jobs
2. Verify API credentials in appsettings.json
3. Ensure audiences exist in your ODP account
4. Check application logs for ODP Audience Sync messages

Cookie not being set

1. Ensure the middleware is registered: app.UseMiddleware<OdpSegmentMiddleware>()
2. Verify the ODP JavaScript snippet is on your site (sets the vuid cookie)
3. Check that HTTPS is enabled (cookie has Secure flag)
4. Check logs for ODP Middleware: Parsed userId messages
5. Use the diagnostic endpoint: GET /api/odp/my-audiences

User not matching any audiences

1. Verify the vuid cookie exists in the browser
2. Use the diagnostic endpoint: GET /api/odp/check-user/{vuid}
3. Check application logs for ODP GraphQL Response

Cache is empty after restart

The cache is in-memory and will be empty after an application restart. The scheduled job runs 1 minute after startup to repopulate it. You can also run it manually from Admin → Scheduled Jobs.

vuid Cookie Format

The ODP JavaScript snippet sets a vuid cookie in this format:

vuid=%7Cauth0|604dc23ae94c1f001c70a8f7|f79e9eca-6920-4cfb-9b5f-622480656f6c

The package automatically:

1. URL-decodes (%7C → |)
2. Splits on | and takes the GUID
3. Removes hyphens → 56a87f1b25b44324aff3b5c9fa12ad1d

This is the format ODP expects for the vuid identifier.

Performance

At 200K+ requests/day:

The criterion reads from the cookie during page render. API calls only happen in the middleware before the page renders, or as a fallback if the cookie is missing.

License

MIT License

Support

https://github.com/bodhibasu/Optimizely.ODP