Skip to main content

For AI agents: a Markdown version of this page is at https://docs.snowplow.io/docs/signals/applications/public-services.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt, and the index for this section is at https://docs.snowplow.io/docs/signals/llms.txt.

Read attributes from websites and apps

Websites and mobile apps can read a service with the public access mode directly, without a Snowplow API token. Use this to personalize a page or screen with the current user's attributes, such as showing recently viewed products or adapting content to engagement level, without building a backend to proxy the request.

Each read returns every attribute in the service for one identifier. Reading a public service works the same way as retrieving attributes with an API token, with these differences:

  • Only services with the public access mode can be read this way. Any other service returns a 404 error.
  • The identifier must be a UUID, and each request reads one identifier
  • Requests are allowed from any origin, and responses are never cached
Public services expose their attributes

Anyone who has an identifier can read the attributes stored for it. Only include attributes that are safe to show to the user they describe, keyed by an identifier the browser or device already holds, such as domain_userid or client_session_user_id. Don't include personal or sensitive data in a public service.

Make a service public​

Set the service's access mode to public in Console or with the Python SDK. See Control who can read a service.

The service must be keyed by the same attribute key that your application reads it by. For web applications, that's usually domain_userid or domain_sessionid. For mobile apps, use the built-in client_session_user_id or client_session_session_id attribute keys, which are based on the identifiers in the mobile trackers' session entity.

Read the service​

Pass the attribute key that the service is keyed by, and the identifier to read it for, such as the current user's ID from the tracker. You'll also need your Signals API URL, from the Signals > Overview page in Console. You don't need any other connection credentials.

Use getServiceAttributes() from the Signals browser plugin, version 0.3.0 or later. To read the service for the current user, pass the domain_userid from the Snowplow browser tracker:

typescript
import { newTracker } from '@snowplow/browser-tracker';
import { getServiceAttributes, ServiceAttributesError } from '@snowplow/signals-browser-plugin';

const tracker = newTracker('sp1', '{{collector_url}}', { appId: 'my-app-id' });

try {
const attributes = await getServiceAttributes({
endpoint: '000000000000.signals.snowplowanalytics.com',
service: 'my_public_service',
attributeKey: 'domain_userid',
identifier: tracker.getDomainUserId(),
});
console.log(attributes.page_views_count); // null if there's no value yet
} catch (e) {
if (e instanceof ServiceAttributesError) {
console.warn(e.status, e.message);
}
}

To read by session, pass domain_sessionid with tracker.getDomainSessionId(), available from version 4.9.0 of the browser tracker.

The function takes these options:

OptionDescriptionTypeRequired?
endpointYour Signals API URLstring✅
serviceThe name of a service with the public access modestring✅
attributeKeyThe attribute key the identifier belongs to, for example domain_userid. For a service keyed by snowplow_id, use one of its lookup identifiersstring✅
identifierThe UUID to read the service forstring✅
timeoutMsHow long to wait for a response, in milliseconds. Defaults to 2000number❌

The function resolves to an object with every attribute in the service by name. The values aren't typed, because the service is defined in Signals and can change without your code changing. Check their shape before you rely on it, for example with a schema library such as Zod.

Handle errors​

Each method reports failures with a status code and a message:

StatusMeaning
400The request didn't have exactly one identifier, the identifier isn't a UUID, or the attribute key doesn't match the service
404The service doesn't exist, isn't published, or doesn't have the public access mode
0No request was sent, for example because Signals isn't configured in the tracker, or no response arrived before the timeout. Only returned by the browser plugin and the mobile trackers

When calling the API directly, error responses have a JSON body with an error message.

If you change a service's access mode, the change can take a few seconds to apply to reads.

Signals free tier and Snowplow CDI

New to Snowplow: the Signals free tier is a hosted environment, with event collection included, capped at 5 million events a month, with no end date or credit card. Snowplow runs it on AWS, in the US or the EU depending on the region you sign up from.

Already run Snowplow CDI: Signals reads events from your existing pipeline, and is deployed in the AWS region you choose. See Set up Signals.

Was this page helpful?