Search, Interaction, Form and Custom

For developers

SEARCH, INTERACTION, FORM, CUSTOM_EVENT, and GAMIFICATION with runtime and type precision. Business meaning: Event Catalog. Operational internals: Popups, Search and Push.

SEARCH

Methods

• events.Search(params)
• direct events.sendEvent({ name: 'SEARCH', ... })

Parameter details

• Required (type) query
• Optional (type) results
• Runtime practice: hooks can send extended keys (type, async, noProcess, dnt, dnp, recommendIds, nested params)

Search phase semantics

Use these patterns consistently so reporting is predictable:

• Before search: send with type: 'instant' while user is typing or opening the search widget.
• After search: non-empty query with type: 'instant' for a completed keyword search.
• Searchandising: send with type: 'faceted' + query when facets/filters are applied to influence merchandising ranking.

Example from useSearch (advanced)

The Event Playground uses short events.Search(...) calls (see tables above). src/hooks/useSearch.tsx shows a fuller sendEvent({ name: 'SEARCH', ... }) shape used in product UIs, including:

• type: 'instant'
• async: true
• noProcess, tryCount, nextPage
• dnt, dnp
• params._search_no_cache_
• recommendIds

INTERACTION

Methods

• events.Interaction(params)
• direct events.sendEvent({ name: 'INTERACTION', ... })

Type-level values

InteractionPayload.type includes:

• impression, click, widget-view, email, push, close, search, sgm-hash

The playground also sends type: 'sms' for SMS campaign clicks; align runtime payloads with your backend contract if you extend beyond the published union.

Runtime transformation

events.Interaction() sends:

• name: 'INTERACTION'
• type as given
• if instanceId is set, the SDK sets interactionId to the same string as instanceId, overwriting any interactionId you passed (see Interaction() in src/classes/events.ts)

So playground rows that show different instanceId and interactionId illustrate intent; on the wire interactionId will match instanceId whenever instanceId is present.

Repository behavior note

src/hooks/useSearch.tsx includes a direct sendEvent path for search interaction shape; prefer this route for custom interaction semantics like search click events.

FORM

Method

events.Form({ formName, fields, instanceId })

Runtime payload shape

• name: FORM
• formName
• fields
• params.instanceId

CUSTOM_EVENT

Method

events.ErrorHandler(error)

Runtime payload shape

• name: CUSTOM_EVENT
• type: error_handler
• params.errorMessage
• params.nextPage

GAMIFICATION

Methods

• events.GamificationWof(params)
• events.GamificationScratch(params)

Runtime behavior

Both methods currently send the same family/type pair:

• name: GAMIFICATION
• type: win

This means method name, not payload shape, differentiates wheel-of-fortune vs scratch at callsite level.

Event Playground (example/src/App.tsx)

Every row below lists the object literal passed into SegmentifyEvents.Interaction(...), SegmentifyEvents.Search(...), and so on. The SDK still merges session/device context, and Interaction rewrites interactionId when instanceId is present (see Runtime transformation above). Inspect the Event Inspector or network to see the final JSON.

Search demos

Button	Payload shape (business fields)
Before Search	{ query: '', type: 'instant' }
After Search	{ query: 'kitchen', type: 'instant' }
Searchandising	{ query: 'kitchen', type: 'faceted', ordering: { page: '1', sort: 'BEST_MATCH' }, trigger: 'keyword', filters: [] }

Interaction demos (search funnel)

Button	Payload shape
Interaction Click	{ type: 'click', instanceId: 'expo-button-list', interactionId: 'interaction-demo' }
Interaction View	{ type: 'widget-view', instanceId: 'expo-button-list', interactionId: 'interaction-demo' }
Before Search Interaction Click	{ type: 'search', instanceId: 'bs_product', interactionId: '0986384' }
Before Search Interaction View	{ instanceId: 'BEFORE_SEARCH', interactionId: 'static', type: 'widget-view' }
Before Search Interaction Impression	{ instanceId: 'BEFORE_SEARCH', interactionId: 'static', type: 'impression' }
After Search Interaction Click	{ type: 'search', instanceId: 'product', interactionId: '0986384', params: { term: 'kitchen' } }
After Search Interaction View	{ instanceId: 'SEARCH', interactionId: 'static', type: 'widget-view' }
AfterSearch Interaction Impression	{ instanceId: 'SEARCH', interactionId: 'static', type: 'impression' }
Searchandising Click	{ type: 'search', instanceId: 'fcs_d36533049a000', interactionId: '0986384' }

The AfterSearch Interaction Impression label matches the string in App.tsx (typo-style spacing). Prefer consistent After Search wording in your own app copy.

Interaction demos (email / SMS / user op)

Button	Payload shape
Email User OP	{ step: 'identify', channel: 'email', type: 'sgm-hash', identity: 'utm_code' }
Email Interaction Click	{ type: 'email', interactionId: 'eml_e3dcb5d02e000', instanceId: 'eml_e3dcb5d02e000' }
SMS Interaction Click	{ type: 'sms', interactionId: 'static', instanceId: 'sms_1dce21709da60000' }

Other single-event demos

Button	Method	Payload (high level)
PageView	PageView	category, subCategory, params
ProductView	ProductView	demo product 0986384 with title, price, oldPrice, image, category, brand, inStock, url, params
Basket View	BasketView	totalPrice, productList (no cartUrl in playground; add in production)
Basket Add / Remove	BasketAdd / BasketRemove	productId, quantity, price
Order Success	Purchase	totalPrice, orderNo, productList, paymentType, discounts, shipment, tax, coupon
BasketClear	BasketClear	no arguments
FavoriteAdd / Remove / View	FavoriteAdd / FavoriteRemove / FavoriteView	productId and/or favoritesList
Identify / Register / LogIn / Logout	Identify / Register / Login / Logout	fixed demo emails and ids (see inspector)
Push Subscribe	Events.subscribePushNotification	{ token } from PushService.getToken()
Push Interaction VIEW / CLICK	Events.pushNotificationInteraction	{ type: 'VIEW' | 'CLICK', instanceId: 'expo-push-view' | 'expo-push-click' }

Use Usage Overview for the button order and links into deeper event reference pages.

Repository usage links

• Search screen sample: example/src/screens/HomeScreen.tsx (with useSearch)
• Search hook (SEARCH via sendEvent, plus sendClick / sendInteraction): src/hooks/useSearch.tsx
• Popup interaction lifecycle: src/hooks/usePopup.tsx
• Operational notes: Popups, Search and Push