Skip to main content

User Attributes

User attributes are typed profile fields your organization defines in the Allegro admin — things like a newsletter opt-in, a favorite topic, or any preference you want a member to control. This guide covers reading and writing them from the browser with the SDK, which is how you'd build a preference center on your site.

Attributes are defined by an operator first. See the User Attributes product guide for how to create them and what the types mean.

Requires a signed-in member

These methods act on the currently authenticated member. Call them after the member has signed in — an unauthenticated visitor has no profile to read or write.

Reading a member's attributes​

allegro.member.getUserAttributes() returns every defined attribute merged with the current member's value, so you can render a whole preference form from one call:

window.allegro.push(async function (allegro) {
    const attributes = await allegro.member.getUserAttributes();

    attributes.forEach(function (attribute) {
        console.log(attribute.slug, attribute.value);
    });
});

Each entry has the attribute's definition plus the member's current value:

FieldTypeDescription
slugstringThe attribute key.
namestringThe human-readable label.
descriptionstring | nullThe optional description.
typestringstring, number, boolean, or enum.
optionsstring[] | nullThe allowed choices, when the type is enum.
valueunknownThe member's current value, or null when none is set.
user_editablebooleanWhether the member may set or clear this attribute themselves.
validation_rulesArray<{ type: string; value: string | number | null; message: string | null }> | nullThe validation rules configured on the attribute, or null when none are set. Mirror these client-side to validate before submitting.

Every defined attribute appears in the list, whether or not the member has set a value for it.

Setting a value​

allegro.member.setUserAttribute(slug, value) sets the value for the current member and resolves with the stored value:

window.allegro.push(async function (allegro) {
    await allegro.member.setUserAttribute('wants-newsletter', true);
});

The value must match the attribute's type — a boolean for a boolean attribute, one of the defined options for an enum attribute, and so on. Text and number attributes can also carry validation rules an operator configures (length, pattern, numeric bounds, and so on). A value that fails the type check or any of these rules is rejected with a 422 VALIDATION_ERROR, and the operator's configured (or default) message is returned under data.errors.value:

{
    "data": {
        "code": "VALIDATION_ERROR",
        "errors": { "value": ["Keep it under 5 characters."] }
    }
}

Because that message is the one the operator wrote for the rule, you can surface it directly to the member. Writing to a slug that isn't a defined attribute is also rejected.

If the attribute's user_editable flag is off, the request is rejected with a 403 USER_ATTRIBUTE_NOT_EDITABLE error — check the flag from getUserAttributes() before showing the field as writable in a preference form.

Setting several values at once​

allegro.member.setUserAttributes(values) takes the values keyed by attribute slug and resolves with the stored values, so a preference form saves in one round trip. A null value clears the member's stored value:

window.allegro.push(async function (allegro) {
    const stored = await allegro.member.setUserAttributes({
        'wants-newsletter': true,
        'display-name': 'Jane',
        color: null, // clears the stored value
    });
});

The call is all-or-nothing: every slug is resolved and every value validated before anything is written, so nothing is saved if any single entry is bad. The three ways a call can fail each name the slugs responsible:

FailureResponse
A slug isn't a defined attribute404 USER_ATTRIBUTE_NOT_FOUND, with the unknown slugs in data.slugs
An attribute's user_editable flag is off403 USER_ATTRIBUTE_NOT_EDITABLE, with the blocked slugs in data.slugs
A value fails its type or validation rules422 VALIDATION_ERROR, with messages keyed values.<slug>

Validation errors carry the operator's configured message for the rule, the same as the single-value endpoint, keyed by the attribute they belong to so a form can show each message against its own field:

{
    "data": {
        "code": "VALIDATION_ERROR",
        "errors": {
            "values.display-name": ["Keep it under 5 characters."],
            "values.color": ["The selected color is invalid."]
        }
    }
}

Clearing a value​

allegro.member.deleteUserAttribute(slug) removes the member's value for an attribute:

window.allegro.push(async function (allegro) {
    await allegro.member.deleteUserAttribute('wants-newsletter');
});

Clearing is subject to the same user_editable check as setting a value, and fails with the same 403 USER_ATTRIBUTE_NOT_EDITABLE error when the attribute isn't editable by the member.

Keeping the session token current​

Setting or clearing values changes the member's session token — attribute values are carried in its user_attributes claim. The SDK stores the freshly-issued token automatically after each write, so a subsequent allegro.member.getJwt() returns a token that reflects the change.