Akamai SBSD Adds a Context Field: What to Change

The Akamai SBSD endpoint has a new field. Alongside the payload, the response now returns a context string, and the endpoint accepts context as an input. Keep the one you get back and send it on every SBSD call after the first.

It is optional today and it will become mandatory. Sending it improves SBSD success rates, and it lets you stop re-sending the script on every call, which is roughly half a megabyte you no longer put on the wire.

Key Takeaways

• The SBSD response now carries a context field next to the payload. The SBSD endpoint also accepts context as an input.
• Your first SBSD call does not change. Send it exactly as you do today, and keep the context from its response.
• On every call after the first, send that context and leave script empty. script and context are mutually exclusive, and a request that sends both is rejected.
• Not sending the script again saves roughly half a megabyte per call, and sending the context improves SBSD success rates.
• Optional today, mandatory soon. We are not putting a date on it, and you will get notice before it changes.

#What changed

This is a schema update. The SBSD endpoint returns one more field, and it takes one more field.

On the response side, next to the payload you already use, there is now a context string. On the request side, there is now a context input that accepts the value you were given.

That is the whole shape of it. The endpoint is the same endpoint, the payload you post to Akamai is still the payload, and the first SBSD call in a flow is byte for byte the call you make today.

#What you need to do

Three steps, and only the second one touches your code in a way you have to think about.

1. Upgrade the SDK. Versions are below. On Go the module path moves to /v3, so this is an import change as well as a version bump.

2. Keep the context from the first response. Your first SBSD call stays as it is, script included. Hold on to the context it returns for the rest of the flow.

3. Send that context on every call after the first, with script empty. Pass the value through unchanged. Do not send the script again.

Go, with the new import path:

import hyper "github.com/Hyper-Solutions/hyper-sdk-go/v3"

// First call: send the script, keep the context from the response.
payload, sbsdContext, err := session.GenerateSbsdData(ctx, &hyper.SbsdInput{
    Index:          0,
    UserAgent:      userAgent,
    Uuid:           uuid,
    PageUrl:        pageUrl,
    OCookie:        oCookie,
    Script:         script,
    AcceptLanguage: acceptLanguage,
    IP:             ip,
})

// Every call after it: send the context, leave Script empty.
payload, sbsdContext, err = session.GenerateSbsdData(ctx, &hyper.SbsdInput{
    Index:          index,
    UserAgent:      userAgent,
    Uuid:           uuid,
    PageUrl:        pageUrl,
    OCookie:        oCookie,
    AcceptLanguage: acceptLanguage,
    IP:             ip,
    Context:        sbsdContext,
})

Python:

# First call: send the script, keep the context from the response.
payload, context = session.generate_sbsd_data(SbsdInput(
    0, user_agent, uuid, page_url, o_cookie, script, accept_language, ip,
))

# Every call after it: send the context, leave script empty.
payload, context = session.generate_sbsd_data(SbsdInput(
    index, user_agent, uuid, page_url, o_cookie, "", accept_language, ip, context,
))

JavaScript, where the constructor argument order is index, uuid, o_cookie, pageUrl, userAgent, script, ip, acceptLanguage, context:

// First call: send the script, keep the context from the response.
let { payload, context } = await generateSbsdPayload(session, new SbsdInput(
    0, uuid, oCookie, pageUrl, userAgent, script, ip, acceptLanguage,
));

// Every call after it: send the context, leave script empty.
({ payload, context } = await generateSbsdPayload(session, new SbsdInput(
    index, uuid, oCookie, pageUrl, userAgent, "", ip, acceptLanguage, context,
)));

You need these SDK versions or newer:

Go       hyper-sdk-go/v3  v3.0.0
Python   hyper-sdk        3.0.0
JS/TS    hyper-sdk-js     4.0.0

On Go, v2 still works and is now marked deprecated. It will not get this field, so treat the /v3 import as part of this change rather than something to do later.

If you use our Playwright wrapper, upgrade to hyper-sdk-playwright 1.0.0-beta.15 and you are done. It passes the context for you. No code changes.

#Script and context are mutually exclusive

Only one of the two goes in a request.

• First SBSD call: script set, context empty.
• Every call after it: context set, script empty.

A request that sends both is rejected, so this is not something you can hedge on by sending the script alongside the context and letting us pick. Clear the script field when you start sending the context.

The payoff for clearing it is immediate. The script is around half a megabyte, and on a flow with several SBSD calls you were sending that again on each one. The context takes its place and is far smaller.

#Timeline

context is optional right now. Omit it and your SBSD calls keep working the way they always have.

It is going to become mandatory. We are not announcing a date today, and you will get notice before the change lands, so nothing you have running is going to stop working without warning.

What we would suggest is not waiting for that notice. The migration is a version bump, one value you hold on to, and one field you stop sending. Doing it now gets you the success rate and the bandwidth, and it takes the deadline off your plate.

#On adding a field at all

We know a new input is a burden. You have to touch working code, redeploy, and re-verify a flow that was fine yesterday. On Go you also have to change an import path, which is the part we like least about this release.

We add fields to these APIs only when there is no good way around it. This one earns its place twice over: success rates go up, and the half megabyte of script you were re-sending on every call goes away.

So this is the whole change: upgrade, keep one string, send it instead of the script.

#If something is unclear

Read this through first, then come and ask. We are in Discord and happy to look at a capture if your integration is doing something the examples do not cover.

Working end-to-end examples for every language and TLS client are in the examples repo, and the API reference is in the Akamai docs.