SDK Events Explained

For developers

A method-by-method, copy-paste walkthrough of the core events. Want the “why” behind each one first? See the Event Catalog (Plain Language).

Read this first

This page is for implementers who want zero guesswork.

For each core SDK event, you get:

• what it means in plain language
• exactly when to send it
• required fields (must send)
• optional fields (nice to have)
• common mistakes (do not do these)
• copy-paste code
• exact example app file references

Source of truth: src/classes/events.ts

What SDK auto-adds to your payload

Most event methods call sendEvent(...) internally. The SDK enriches your payload with fields like:

• userId, sessionId
• device, os, osversion
• currency, lang
• testMode
• email (if known in SDK storage)

You should send business fields only (product/order/search/identity data).

Core integration order (recommended)

1. Initialize + navigation (triggerInitialPageView, navigationObserver)
2. Product discovery (ProductView, Search)
3. Cart behavior (BasketAdd, BasketRemove, BasketView)
4. Conversion (Purchase)
5. Identity (Register, Login, Logout, Identify)
6. Push (subscribePushNotification, pushNotificationInteraction)

1) Navigation and discovery

PageView

What it does: tells Segmentify which screen/page user is on.

When to send:

• app first opens
• route changes

Required fields: none in type Optional fields: category, subCategory, params

Common mistakes:

• only sending once on app start and never on route changes

import { Initialize } from '@segmentify/react-native-v2';

const sdk = new Initialize(SEGMENTIFY_CONFIGURATION);
sdk.triggerInitialPageView('Home');
// and in navigation container:
// onStateChange={sdk.navigationObserver}

SDK method reference: src/classes/events.ts (PageView) Example app reference: example/src/App.tsx (Event Playground PageView button; in your app, also attach navigationObserver on NavigationContainer for route-driven page views)

ProductView

What it does: marks that user opened a product detail page.

When to send: when product data is ready and PDP is shown.

Required fields: productId Optional fields: title, price, oldPrice, brand, image, inStock, labels, params

Common mistakes:

• sending productName only (SDK payload type uses title)
• firing before product is loaded

import { Events } from '@segmentify/react-native-v2';

const events = new Events();
await events.ProductView({
  productId: product.id,
  title: product.name,
  price: product.price,
  oldPrice: product.originalPrice,
  category: product.category,
  image: product.image,
  inStock: product.inStock,
});

SDK method reference: src/classes/events.ts (ProductView) Example app reference: example/src/App.tsx (ProductView button); example/src/screens/ProductScreen.tsx for a screen-level pattern

Search

What it does: records user search intent.

When to send: each real search action (manual submit or selected auto-search trigger). Important: If do you want to understand search enabled or disabled, you must send a pageview request first. In the response you’ll receive a field which it will help you to understand search enabled or disabled.

Before / after / searchandising (playground-aligned):

• Before search: query: '' and type: 'instant' (user opened search or has not committed a query yet).
• After search: non-empty query and type: 'instant' (plain keyword search completed).
• Searchandising: non-empty query, type: 'faceted', plus optional ordering, trigger, filters when your UI applies facets or merchandising rules.

Field query: send an empty string for before-search; the SDK and reporting expect that pattern, not an omitted property.

Optional fields: type, results, ordering, trigger, filters, params, and other keys your integration adds (see useSearch for a richer sendEvent shape).

Common mistakes:

• omitting type: 'instant' / 'faceted' when your dashboard expects a phase
• firing only widget Interaction events and never a Search for the same user action

import { Events } from '@segmentify/react-native-v2';

const events = new Events();
// After search
await events.Search({
  query: 'kitchen',
  type: 'instant',
});

SDK method reference: src/classes/events.ts (Search) Example app reference: example/src/App.tsx (Before Search, After Search, Searchandising buttons). For a hook-driven SEARCH + INTERACTION pipeline, see src/hooks/useSearch.tsx (used by example/src/screens/HomeScreen.tsx).

2) Basket and checkout

BasketAdd

What it does: user adds product to cart or increases quantity.

When to send: immediately after cart mutation succeeds.

Required fields: productId, quantity Optional fields: price

await events.BasketAdd({
  productId: item.productId,
  quantity: item.quantity,
  price: item.price,
});

SDK method reference: src/classes/events.ts (BasketAdd) Example app reference: shared/hooks/useCart.tsx

BasketRemove

What it does: user removes a product from cart.

When to send: right after item is removed from state/backend.

Required fields: productId, quantity Optional fields: price

await events.BasketRemove({
  productId,
  quantity: 1,
});

SDK method reference: src/classes/events.ts (BasketRemove) Example app reference: shared/hooks/useCart.tsx

BasketView

What it does: basket screen viewed (funnel start signal).

When to send: when basket screen becomes visible with current cart snapshot.

Required fields: totalPrice, productList Optional fields: cartUrl (recommended in production deep links; optional in BasketViewPayload)

Common mistakes:

• sending from component body (fires on every render)
• omitting cartUrl when your analytics team expects a stable basket URL (the Event Playground Basket View demo omits it on purpose to keep the snippet short)

await events.BasketView({
  totalPrice: cart.totalPrice,
  cartUrl: 'shopapp://basket',
  productList: cart.items.map((item) => ({
    productId: item.productId,
    quantity: item.quantity,
    price: item.price,
  })),
});

SDK method reference: src/classes/events.ts (BasketView) Example app reference: example/src/App.tsx (Basket View); example/src/screens/BasketScreen.tsx

Purchase

What it does: completed order event (critical conversion signal).

When to send: once, after successful checkout.

Required fields: totalPrice, orderNo, productList Optional fields: paymentType, discounts, shipment, tax, coupon

Common mistakes:

• using orderId key instead of orderNo
• firing in render path and duplicating event

await events.Purchase({
  orderNo: orderIdFromRoute,
  totalPrice: cart.finalTotal,
  productList: cart.items.map((item) => ({
    productId: item.productId,
    quantity: item.quantity,
    price: item.price,
  })),
});

SDK method reference: src/classes/events.ts (Purchase) Example app reference: example/src/App.tsx (Order Success); example/src/screens/CheckoutSuccessScreen.tsx (maps navigation param orderId into payload field orderNo)

3) Identity events

Register

What it does: user completed sign-up.

When to send: after registration succeeds.

Required fields: email Optional fields: phone, emailNtf, smsNtf, whatsappNtf, profile fields

await events.Register({
  email: formData.email,
  firstName: formData.firstName,
  lastName: formData.lastName,
  phone: formData.phone,
});

SDK method reference: src/classes/events.ts (Register) Example app reference: example/src/App.tsx (Register); example/src/screens/RegisterScreen.tsx

Login (sign-in)

What it does: user signed in.

When to send: after login/auth success.

Required fields: email

await events.Login({
  email: formData.email,
});

SDK method reference: src/classes/events.ts (Login) Example app reference: example/src/App.tsx (LogIn button); example/src/screens/LoginScreen.tsx (after mock login(), with Initialize.setUser and events.Login)

Logout

What it does: user signed out.

When to send: right before or right after local logout (pick one and keep it consistent).

Required fields: email

await events.Logout({
  email: user.email,
});

SDK method reference: src/classes/events.ts (Logout) Example app reference: example/src/App.tsx (Logout button); shared/hooks/useAuth.tsx (logout); example/src/screens/ProfileScreen.tsx when that flow is wired

Identify

What it does: user profile/preferences updated.

When to send: profile edit save success.

Common fields: email, phone, emailNtf, smsNtf, whatsappNtf

await events.Identify({
  email: 'expo-demo@segmentify.com',
  externalId: 'expo-demo-user',
  source: 'email-collection',
  isLogin: true,
});

This mirrors the Identify button in the Event Playground; in production, send your real profile and consent fields (see User and Wishlist).

SDK method reference: src/classes/events.ts (Identify) Example app reference: example/src/App.tsx (Identify); example/src/screens/EditProfileScreen.tsx

3.5) Customer Data Platform events

CDP methods enrich the Segmentify user profile without using USER_OPERATIONS steps. Full reference: Customer Data Platform Events.

UserTraits

What it does: sends arbitrary profile traits (USER_TRAITS).

When to send: after profile or preference data changes.

Common fields: email, gender, age, location, fullName, loyalty_level, *Consent

await events.UserTraits({
  email: 'product@segmentify.com',
  gender: 'male',
  loyalty_level: 'gold',
  emailConsent: 'SUBSCRIBED',
});

Example app reference: example/src/App.tsx (User Traits)

IdentifyUser

What it does: identifies a known user (USER_IDENTIFY) with change-based deduplication.

When to send: when profile data changes; skipped when payload matches the last successful snapshot.

Example app reference: example/src/App.tsx ([CDP] Identify User)

RegisterUser / LoginUser / LogoutUser

What they do: CDP lifecycle events (USER_REGISTER, USER_LOGIN, USER_LOGOUT) without SEGMENTIFY_USER storage side effects.

Example app reference: example/src/App.tsx ([CDP] Register User, [CDP] Login User, [CDP] Logout User)

SubscribeUser / UnsubscribeUser

What they do: channel subscription and unsubscription (USER_SUBSCRIBE, USER_UNSUBSCRIBE).

Channels: email, web_push, whatsapp, sms, call

await events.SubscribeUser({
  channel: 'whatsapp',
  phoneNumber: '1234567890',
});

await events.UnsubscribeUser({
  channel: 'sms',
  phoneNumber: '1234567890',
});

Example app reference: example/src/App.tsx ([CDP] Email / WhatsApp / SMS / Call Subscribe and Unsubscribe buttons)

4) Push events

subscribePushNotification

What it does: registers device token for push delivery.

When to send: when permission is granted and token is available.

Required fields: token Optional fields: providerType (FIREBASE or APNS)

await Events.subscribePushNotification({
  token: fcmToken,
});

SDK method reference: src/classes/events.ts (subscribePushNotification) Example app reference: example/src/App.tsx (Push Subscribe — uses Events static method with { token } from PushService); token lifecycle and receive/open hooks: example/src/services/PushService.ts

pushNotificationInteraction

What it does: tracks push engagement.

When to send:

• VIEW when notification is received/seen
• CLICK when user taps notification

Required fields: type (VIEW or CLICK) Optional fields: instanceId

await Events.pushNotificationInteraction({
  type: 'CLICK',
  instanceId: 'expo-push-click',
});

SDK method reference: src/classes/events.ts (pushNotificationInteraction) Example app reference: example/src/App.tsx (Push Interaction VIEW / CLICK); example/src/services/PushService.ts (automatic VIEW / CLICK on receive and open when not in Expo Go)

Example app event map

The running example (example/index.js) loads example/src/App.tsx, an Event Playground with one button per demo event. Use the in-app Event Inspector to see the exact JSON sent (after SDK enrichment, inspect network or logging as needed) and the normalized HTTP response.

Playground area	SDK entry points	Also see
Page / product	PageView, ProductView	Page and Product, example/src/screens/ProductScreen.tsx
Generic widget	Interaction (click, widget-view)	Search, Interaction, Form and Custom
Search phases	Search (instant / faceted)	Same page, src/hooks/useSearch.tsx, example/src/screens/HomeScreen.tsx
Search widgets	Interaction (before/after/searchandising rows)	Playground table in Search, Interaction, Form and Custom
Basket / order	BasketView, BasketAdd, BasketRemove, Purchase, BasketClear	Checkout and Basket, shared/hooks/useCart.tsx, basket/checkout screens
Wishlist	FavoriteAdd, FavoriteRemove, FavoriteView	User and Wishlist, shared/hooks/useWishlist.tsx
Identity	Identify, Register, Login, Logout	User and Wishlist, auth/register/profile screens
Customer Data Platform	UserTraits, IdentifyUser, RegisterUser, LoginUser, LogoutUser, SubscribeUser, UnsubscribeUser	Customer Data Platform
Push	Events.subscribePushNotification, Events.pushNotificationInteraction	Push Notification Events, example/src/services/PushService.ts
Email / SMS campaigns	Interaction (sgm-hash, email, sms)	Search, Interaction, Form and Custom

Continue reading

• Page and Product
• Checkout and Basket
• User and Wishlist
• Search, Interaction, Form and Custom
• Push Notifications
• Customer Data Platform
• Known Gotchas