Event Tracking API

No SDK Required

One HTTP call does three things at once: records the behavior, registers the user, and updates their device token. Zero dependencies, any language, any platform.

Events are the foundation of SmartAppPush. Every event you send simultaneously records user behavior, creates or updates the user profile, and registers the device for push delivery. No separate registration calls needed.

Endpoint

endpoint

http

POST https://api.smartapppush.ai/events

Authentication: api_key in the request body (no Authorization header needed).

Request Example

request body

json

{
  "tenant_id": "your_tenant_id",
  "api_key": "your_app_api_key",
  "app_user_id": "user_123",
  "event_name": "purchase_completed",
  "event_time": "2026-03-29T14:30:00+03:00",
  "device_token": "fcm_or_onesignal_device_token",
  "platform": "android",
  "push_permission_granted": true,
  "timezone": "Europe/Istanbul",
  "language": "tr",
  "country": "TR",
  "session_id": "sess_abc123",
  "params": {
    "product_id": "SKU-9001",
    "amount": 49.99,
    "currency": "USD"
  }
}

Response

200 OK

json

{
  "fingerprint": "a1b2c3d4e5f6..."
}

Field Reference

Field	Required	Description
tenant_id	Yes	Your account ID
api_key	Yes	Your app's API key
app_user_id	No	Your internal user ID. If empty, an anonymous ID is auto-generated
event_name	Yes	Event name (e.g., app_opened, purchase_completed)
event_time	Yes	RFC 3339 timestamp with timezone offset
device_token	Yes	FCM registration token or OneSignal subscription ID. For FCM: token from onNewToken() (Android) or messaging:didReceiveRegistrationToken: (iOS) — can rotate. For OneSignal: stable subscription ID from the OneSignal SDK
platform	Yes	One of: android, ios, web
push_permission_granted	Yes	Must be true for the device to receive pushes
timezone	Yes	IANA timezone (e.g., Europe/Istanbul, America/New_York)
language	Yes	ISO 639-1 language code (e.g., en, tr, de)
country	Yes	ISO 3166-1 alpha-2 country code (e.g., US, TR, DE)
session_id	Yes	Session identifier for grouping events within a single app session
params	No	Event-specific data for targeting and analytics
context	No	Environment metadata (app version, OS, screen)

params vs context

params — Event-specific data (product ID, amount, category). Used for campaign targeting and analytics. Put anything you want to filter by here.

context — Environment metadata (app version, OS, screen). Stored for reference but not used in targeting rules. Use for debugging and diagnostics only.

Why push_permission_granted Matters

Always send this field. Users can toggle notifications in device settings at any time. SmartAppPush only delivers to devices where push_permission_granted: true. If you omit this field, it defaults to false and the device will never receive pushes.

Deduplication

Every event gets a SHA-256 fingerprint. If you accidentally send the same event twice (network retry), the duplicate is silently ignored. The fingerprint is returned in the response for debugging.

Error Responses

Status	Meaning
400	Validation error — missing fields, invalid format, unknown API key
503	Server overloaded — retry after a short delay

System Event Reference

SmartAppPush ships with predefined system events. Use these as-is or send any custom event name — custom events are automatically discovered from your event stream.

Onboarding (4 events)+

Event Name	Description	Useful Params
onboarding_displayed	Onboarding screen shown	screen_index, variant
onboarding_step_completed	User completed a step	step, step_name
onboarding_completed	User finished onboarding	duration_seconds, steps_count
onboarding_skipped	User skipped onboarding	skipped_at_step

App Lifecycle (2 events)+

Event Name	Description	Useful Params
app_opened	App opened	source (notification, deeplink, organic)
screen_viewed	User viewed a screen	screen_name, previous_screen

Authentication (5 events)+

Event Name	Description	Useful Params
login_page_displayed	Login screen shown	—
logged_in	User authenticated	method (email, google, apple)
sign_up_started	User initiated registration	method
sign_up_completed	User finished registration	method
logged_out	User signed out	—

E-Commerce (15 events)+

Event Name	Description	Useful Params
product_viewed	Viewed product detail	product_id, category, price
product_list_viewed	User browsed a product listing/category	category, list_name, item_count
add_to_cart	Item added to cart	product_id, quantity, price, currency
remove_from_cart	Item removed from cart	product_id
cart_viewed	User opened cart	item_count, cart_total
begin_checkout	Started checkout	cart_total, item_count, currency
checkout_abandoned	Left checkout incomplete	cart_total, step
payment_failed	Payment unsuccessful	error_code, payment_method
purchase_completed	Transaction completed	order_id, amount, currency, item_count
coupon_applied	Discount code applied	coupon_code, discount_amount
coupon_failed	Coupon code was invalid or expired	coupon_code, reason
refund_requested	User initiated refund	order_id, amount, reason
order_status_viewed	User checked order tracking	order_id, status
wishlist_added	Item saved to wishlist	product_id, category
wishlist_removed	Item removed from wishlist	product_id

Search & Discovery (5 events)+

Event Name	Description	Useful Params
search_performed	User searched	query, results_count
search_result_clicked	Tapped a search result	query, result_position, result_id
search_no_results	Empty search results	query
category_browsed	Browsed a category	category_name, item_count
filter_applied	Applied filters	filter_type, filter_value

Subscription & Monetization (10 events)+

Event Name	Description	Useful Params
paywall_displayed	Paywall shown	source, variant
paywall_dismissed	User closed paywall without action	source, time_spent_seconds
trial_started	Free trial began	plan, duration_days
trial_ended	Trial expired	plan, converted
subscription_started	Subscription purchased	plan, price, currency, period
subscription_renewed	Subscription renewed	plan, price, period
subscription_cancelled	Subscription cancelled	plan, reason
subscription_expired	Subscription access ended	plan
in_app_purchase_completed	One-time IAP completed	product_id, amount, currency
billing_issue_detected	Payment method failed	plan, error_code

Push Notifications (6 events)+

Event Name	Description	Useful Params
push_permission_granted	User allowed push	—
push_permission_denied	User denied push	—
push_received	Push delivered to device	campaign_id, message_id
push_opened	User tapped push	campaign_id, message_id
push_dismissed	User dismissed push	campaign_id
notification_settings_changed	User modified notification preferences	channel, enabled

Content & Engagement (7 events)+

Event Name	Description	Useful Params
content_viewed	User consumed content	content_id, content_type, duration_seconds
content_completed	User finished content	content_id, completion_percent
feature_used	Engaged with a feature	feature_name, screen_name
feature_discovered	First time using feature	feature_name
rating_submitted	User rated something	target_id, target_type, rating
review_submitted	User wrote a review	target_id, target_type, rating
feedback_submitted	In-app feedback sent	feedback_type, screen_name

User Profile & Preferences (4 events)+

Event Name	Description	Useful Params
profile_completed	User filled all required profile fields	—
profile_updated	User changed profile information	fields_updated
language_changed	User changed app language	from_language, to_language
preferences_updated	User changed app preferences	preference_key, new_value

Social & Virality (3 events)+

Event Name	Description	Useful Params
content_shared	Shared content externally	content_id, share_method
invite_sent	Invited someone to app	invite_method
referral_completed	Invited user signed up	referrer_user_id

Friction & Errors (4 events)+

Event Name	Description	Useful Params
error_encountered	User hit an error	error_code, error_message, screen_name
form_abandoned	Left form incomplete	form_name, abandoned_at_step
deep_link_failed	Deep link failed	deep_link_url, error_reason
permission_denied	Denied system permission	permission_type

Custom events welcome.Send any event name you want — SmartAppPush automatically discovers and registers it for your app. System events above are just a starting point.

AI Coding Guides Developer Push API