◼️User markers (tags)

This document provides an overview of the three distinct types of tags — Core: user markers (core_tags), Core: external markers (core_external_markers), and Core: JS markers (core_public_tags) — used within our CRM automation software.

These markers are pivotal in segmenting users and tailoring campaigns, automation rules, and gamification entities.

Looking for dynamic content snippet tags in communication templates? See Label tags for template and content text replacement options.

Usage of markers in the segmentation

Core: user markers (core_tags)

These markers are internally managed within the Smartico system. They can be updated automatically through Smartico mechanics like Campaigns, Automation rules, and Gamification rewards, or manually directly from the player profile in the CRM tab.

Setting/removing markers from the campaign flow

Markers visibility on the CRM profile screen

Core: external markers (core_external_markers)

External Markers are sourced externally via APIs (or through database replication, Kafka, or RabbitMQ feeds). They are not updated by Smartico internal mechanics, meaning the integrated platform remains the single source of truth.

In case you want to update external markers from the API, you can use this type of payload when calling Smartico REST API (you can find full documentation of API and security keys in the Tools \ REST API in the Smartico Back Office)

[
    {
        "eid": "99dcc07c-17f6-418e-b574-c91ffe77d18e",
        "event_date": 1717508861954,
        "ext_brand_id": "spacex",
        "user_ext_id": "test61323352",
        "event_type": "update_profile",
        "payload": {
            "core_external_markers": [
                "Test with API",
                "Marker X"
            ]
        }
    }
]

See updates in the markers, and how they are delivered into the Smartico system. The same approach is working for JS Markers and User markers

Incremental Updates (Add, Remove, Clear)

When sending updates via the REST API or integrations, passing a plain array replaces the user's entire marker list. To modify markers incrementally without overwriting existing ones, use prefix operators in the property name:

• Add markers (+ prefix): "+core_external_markers": ["VIP"] appends new markers to the existing list.

• Remove markers (- prefix): "-core_external_markers": ["TEST"] removes specific markers while keeping others intact.

• Clear all markers (! prefix): "!core_external_markers": null removes all markers from the user.

• Full replacement (no prefix): "core_external_markers": ["A", "B"] overwrites all existing markers with the new list.

These prefix operators apply equally to core_external_markers, core_external_markers_2, core_external_segment, core_tags, and core_public_tags.

In addition to core_external_markers, Smartico provides two additional external marker properties: core_external_markers_2 and core_external_segment.

Both hold arrays of string values and serve the same purpose as the primary property. They are typically used when an operator wants to separate different categories of markers rather than grouping them into a single list.

Core: JS markers (core_public_tags)

JS Markers can be manipulated from the front-end using JavaScript and within the Smartico system through campaigns or automation rules.

It is important that these tags are exposed to the front-end, so they can be used to make changes in the front-end UI based on the presence/absence of the specific tags. The APIs to read/update tags are explained in "Extended Integration"

// to get JS markers on the front-end
// if the marker is set from the Campaign/Automation rule
// the callback 'props_change' will be triggered in the realtime
_smartico.on('props_change', function(props) {
    if (props.core_public_tags !== undefined) {
        // note that the passed object is an array 
        // with upper-cased markers of users
        console.log('List of user tags', props.core_public_tags.join(','));
    }
});

// to update tags from the front-end
_smartico.event('core_public_tags_update', { core_public_tags: ['A', 'B'] } );

// Alternatively, use the built-in SDK helper method for granular operations:
_smartico.updatePublicTags('add', ['VIP']);         // Appends tags
_smartico.updatePublicTags('remove', ['TEST']);     // Removes specific tags
_smartico.updatePublicTags('replace', ['A', 'B']);  // Overwrites all public tags
_smartico.updatePublicTags('clear');                // Clears all public tags

Public tags are automatically normalized to uppercase strings in the SDK and on the server.

Summary

Marker type	Source of data	Usage
Core: user markers	Smartico Campaigns, Automation rules, Gamification rewards (Missions and Badges), and manual update from CRM profile	Segmentation on Smartico side
Core: external markers	Integrated platform via API, Replica DB or Kafka/RabbitMQ	Segmentation on Smartico side
Core: JS Markers	Smartico Campaigns and Rules + from the front-end with JavaScript	Segmentation on Smartico side + Visible in the front-end JavaScript API

Note: all users with corresponding markers are available for export from the Smartico Data warehouse, you can read about DWH here

Frequently Asked Questions

Are user markers and tags case-sensitive?

No. Smartico normalizes all marker strings to uppercase upon receipt and during evaluation. For example, setting "vip" or "VIP" assigns the marker VIP.

How can I add a marker via API without removing existing markers on the player?

Use the + prefix in the property name within the update_profile payload (e.g., { "+core_external_markers": ["VIP"] }). Sending the property name without a prefix replaces the existing array entirely.

Can missions and badges award user markers to players?

Yes. Missions and badges can be configured with completion rewards such as Mark User, Unmark User, Set JS Markers, or Remove JS Markers to update markers automatically upon completion.

Can user markers be imported in bulk via CSV?

Yes. When importing user segments via CSV, you can include the core_tags column formatted as a JSON string array (e.g., ["VIP", "TEST"]). Note that uploading via CSV completely overwrites the user's existing tags.

What is the difference between User Markers and Label Tags?

User markers (core_tags, core_external_markers, core_public_tags) are attributes attached to individual player profiles used for segmentation and automation routing. Label Tags are centralized content snippets used in email, SMS, and banner templates.