Events - Despia Documentation

Installation

Bundle
CDN

npm install despia-native

import despia from 'despia-native';

<script src="https://cdn.jsdelivr.net/npm/despia-native/index.min.js"></script>

Fire any in-app event from your web layer using despia("appsflyer://log_event?..."). Standard af_ prefixed events are automatically mapped to Meta and TikTok conversion events based on your dashboard partner configuration. Custom events appear only in AppsFlyer for funnel and retention analysis.

event_values must always be a JSON stringified and URI encoded object. Always use encodeURIComponent(JSON.stringify(...)). Event names are case-sensitive. Use only lowercase alphanumeric characters and underscores. There is a limit of 300 unique event names per day.

Standard AF Events

These events use the af_ prefix and are automatically mapped to Meta and TikTok conversion events. Use them for any action you want to optimize ad campaigns against.

af_complete_registration

Records when a user completes sign up. Maps to Meta CompleteRegistration and TikTok CompleteRegistration.

const registration = {
    "af_registration_method": "email"
}
despia("appsflyer://log_event?event_name=af_complete_registration&event_values=" + encodeURIComponent(JSON.stringify(registration)))

af_registration_method

string

af_login

Records when a user logs in.

const login = {
    "af_registration_method": "facebook"
}
despia("appsflyer://log_event?event_name=af_login&event_values=" + encodeURIComponent(JSON.stringify(login)))

af_registration_method

string

af_purchase

Records a purchase and associates revenue. Maps to Meta Purchase and TikTok CompletePayment. The most important event for ROAS optimization.

const purchase = {
    "af_revenue": 9.99,
    "af_currency": "USD",
    "af_content_id": "pro_plan",
    "af_content_type": "subscription",
    "af_quantity": 1,
    "af_order_id": "order_abc123"
}
despia("appsflyer://log_event?event_name=af_purchase&event_values=" + encodeURIComponent(JSON.stringify(purchase)))

af_revenue

number

required

Total purchase amount. Counted as real revenue in AppsFlyer. No commas, currency signs, or text. Supports up to 5 decimal places. Use negative values for refunds.

af_currency

string

required

3-character ISO 4217 code, e.g. "USD", "EUR", "AED". Defaults to "USD" if omitted.

af_content_id

string

ID of the purchased item or product, e.g. "pro_plan", "sku_123"

af_content_type

string

Category of the purchased item, e.g. "subscription", "course", "item"

af_quantity

number

Number of items purchased

af_order_id

string

Your internal order ID for deduplication

Do not use af_revenue if you have an ROI360 subscription and use the purchase connector. This causes duplicate revenue reporting in your dashboard.

af_start_trial

Records the start of a free trial. Maps to Meta StartTrial and TikTok Subscribe.

const trial = {
    "af_price": 0,
    "af_currency": "USD"
}
despia("appsflyer://log_event?event_name=af_start_trial&event_values=" + encodeURIComponent(JSON.stringify(trial)))

af_price

number

Price of the trial. Use af_price not af_revenue here. af_price is not counted as revenue and is the correct parameter for Meta’s StartTrial mapping.

af_currency

string

3-character ISO 4217 code. Defaults to "USD" if omitted.

af_subscribe

Records a paid subscription purchase. Maps to Meta Subscribe and TikTok Subscribe.

const subscription = {
    "af_price": 9.99,
    "af_currency": "USD",
    "af_content_id": "pro_monthly"
}
despia("appsflyer://log_event?event_name=af_subscribe&event_values=" + encodeURIComponent(JSON.stringify(subscription)))

af_price

number

Subscription price per period. Not counted as revenue. Use af_revenue if you also want to record this as revenue in AppsFlyer.

af_currency

string

3-character ISO 4217 code. Defaults to "USD" if omitted.

af_content_id

string

ID of the subscription plan, e.g. "pro_monthly", "annual_plan"

af_add_to_cart

Records when a user adds an item to their cart. Maps to Meta AddToCart and TikTok AddToCart.

const addToCart = {
    "af_content_id": "item_42",
    "af_content_type": "clothing",
    "af_price": 19.99,
    "af_currency": "USD",
    "af_quantity": 1
}
despia("appsflyer://log_event?event_name=af_add_to_cart&event_values=" + encodeURIComponent(JSON.stringify(addToCart)))

af_content_id

string

ID of the item added to cart

af_content_type

string

Category of the item

af_price

number

Price of the individual item. Not counted as revenue.

af_currency

string

3-character ISO 4217 code. Defaults to "USD" if omitted.

af_quantity

number

Quantity added to cart

af_initiated_checkout

Records when a user begins the checkout flow. Maps to Meta InitiateCheckout and TikTok InitiateCheckout.

const checkout = {
    "af_revenue": 29.99,
    "af_currency": "USD",
    "af_num_items": 2,
    "af_content_id": "cart_checkout"
}
despia("appsflyer://log_event?event_name=af_initiated_checkout&event_values=" + encodeURIComponent(JSON.stringify(checkout)))

af_revenue

number

Total cart value at checkout. Counted as revenue if included.

af_currency

string

3-character ISO 4217 code. Defaults to "USD" if omitted.

af_num_items

number

Total number of items in the cart

af_content_id

string

Identifier for the checkout session or cart

af_content_view

Records when a user views a piece of content. Maps to Meta ViewContent and TikTok ViewContent.

const contentView = {
    "af_content_id": "product_123",
    "af_content_type": "product"
}
despia("appsflyer://log_event?event_name=af_content_view&event_values=" + encodeURIComponent(JSON.stringify(contentView)))

af_content_id

string

ID of the content viewed, e.g. a product ID, profile ID, or article ID

af_content_type

string

Category of the content, e.g. "product", "article", "collection"

af_price

number

Price associated with the content if applicable

af_currency

string

3-character ISO 4217 code. Defaults to "USD" if omitted.

af_search

Records a search event. Maps to Meta Search and TikTok Search.

const search = {
    "af_search_string": "running shoes"
}
despia("appsflyer://log_event?event_name=af_search&event_values=" + encodeURIComponent(JSON.stringify(search)))

af_search_string

string

The search query entered by the user

af_share

Records when a user shares content.

const share = {
    "channel": "instagram"
}
despia("appsflyer://log_event?event_name=af_share&event_values=" + encodeURIComponent(JSON.stringify(share)))

channel

string

Platform shared to, e.g. "instagram", "whatsapp", "twitter"

af_invite

Records when a user sends an invite or referral.

const invite = {
    "channel": "sms"
}
despia("appsflyer://log_event?event_name=af_invite&event_values=" + encodeURIComponent(JSON.stringify(invite)))

channel

string

Channel the invite was sent through, e.g. "sms", "email", "whatsapp"

af_tutorial_completion

Records when a user completes a tutorial or onboarding step. Maps to Meta CompleteTutorial.

const tutorial = {
    "af_success": true,
    "af_tutorial_name": "step_2"
}
despia("appsflyer://log_event?event_name=af_tutorial_completion&event_values=" + encodeURIComponent(JSON.stringify(tutorial)))

af_success

boolean

Whether the tutorial was completed successfully

af_tutorial_name

string

Name or identifier of the tutorial step

af_level_achieved

Records when a user reaches a new level. Maps to Meta AchieveLevel and TikTok AchieveLevel.

const level = {
    "af_level": 5
}
despia("appsflyer://log_event?event_name=af_level_achieved&event_values=" + encodeURIComponent(JSON.stringify(level)))

af_level

number

The level number achieved

Custom Events

These events do not map to Meta or TikTok but appear in your AppsFlyer dashboard for funnel and retention analysis. Name them anything using lowercase alphanumeric characters and underscores.

profile_created

const profileCreated = {
    "method": "email"
}
despia("appsflyer://log_event?event_name=profile_created&event_values=" + encodeURIComponent(JSON.stringify(profileCreated)))

method

string

How the profile was created, e.g. "email", "google", "apple"

onboarding_step

const onboardingStep = {
    "step": 1,
    "name": "select_interests"
}
despia("appsflyer://log_event?event_name=onboarding_step&event_values=" + encodeURIComponent(JSON.stringify(onboardingStep)))

step

number

Step number in the onboarding flow

name

string

Name of the step, e.g. "select_interests", "upload_photo"

onboarding_complete

const onboardingComplete = {
    "steps_skipped": 0,
    "duration_s": 42
}
despia("appsflyer://log_event?event_name=onboarding_complete&event_values=" + encodeURIComponent(JSON.stringify(onboardingComplete)))

steps_skipped

number

Number of onboarding steps the user skipped

duration_s

number

Total time to complete onboarding in seconds

subscription_start

const subscriptionStart = {
    "plan": "pro",
    "trial": true,
    "price": 9.99
}
despia("appsflyer://log_event?event_name=subscription_start&event_values=" + encodeURIComponent(JSON.stringify(subscriptionStart)))

plan

string

Plan name, e.g. "pro", "basic", "annual"

trial

boolean

Whether the subscription started with a trial period

price

number

Price of the plan

referral_sent

const referralSent = {
    "code": "REF123",
    "channel": "whatsapp"
}
despia("appsflyer://log_event?event_name=referral_sent&event_values=" + encodeURIComponent(JSON.stringify(referralSent)))

code

string

The referral code sent

channel

string

Channel used, e.g. "whatsapp", "sms", "email"

streak_achieved

const streakAchieved = {
    "days": 7
}
despia("appsflyer://log_event?event_name=streak_achieved&event_values=" + encodeURIComponent(JSON.stringify(streakAchieved)))

days

number

Number of consecutive days in the streak

content_viewed

const contentViewed = {
    "content_id": "episode_123",
    "type": "episode"
}
despia("appsflyer://log_event?event_name=content_viewed&event_values=" + encodeURIComponent(JSON.stringify(contentViewed)))

content_id

string

ID of the content item

type

string

Type of content, e.g. "episode", "article", "video"

post_liked

const postLiked = {
    "post_id": "post_456",
    "creator_id": "user_789"
}
despia("appsflyer://log_event?event_name=post_liked&event_values=" + encodeURIComponent(JSON.stringify(postLiked)))

post_id

string

ID of the post that was liked

creator_id

string

ID of the user who created the post

video_completed

const videoCompleted = {
    "video_id": "v1",
    "duration_s": 180
}
despia("appsflyer://log_event?event_name=video_completed&event_values=" + encodeURIComponent(JSON.stringify(videoCompleted)))

video_id

string

ID of the video that was completed

duration_s

number

Duration of the video in seconds

feature_used

const featureUsed = {
    "feature": "dark_mode"
}
despia("appsflyer://log_event?event_name=feature_used&event_values=" + encodeURIComponent(JSON.stringify(featureUsed)))

feature

string

Name of the feature used, e.g. "dark_mode", "notifications", "filters"

Frequently Asked Questions

What is the difference between af_price and af_revenue?

af_revenue is counted as real revenue in AppsFlyer and reported in your dashboard and raw data. Use it for actual purchases. af_price is a monetary value that is NOT counted as revenue. Use it for events like af_add_to_cart or af_start_trial where you want to pass a price but not record revenue. For Meta’s StartTrial mapping specifically, use af_price not af_revenue.

Do I need to map events in the AppsFlyer dashboard?

For standard af_ events, AppsFlyer maps them automatically to Meta and TikTok. For custom events, you need to add them manually in Configuration > Integrated Partners > [Partner] > In-App Events if you want them postbacked to partners.

Can I send multiple items in a single purchase event?

Yes. Use af_content_list with a stringified array of IDs and af_content with a stringified array of objects each containing id and quantity. Do not include af_content_id in the same event when using af_content_list.

How do I record a refund or cancellation?

Fire an af_purchase event with a negative af_revenue value and a custom event name like cancel_purchase:

const refund = {
    "af_revenue": -9.99,
    "af_currency": "USD",
    "af_content_id": "pro_plan"
}
despia("appsflyer://log_event?event_name=cancel_purchase&event_values=" + encodeURIComponent(JSON.stringify(refund)))

Resources

NPM Package

Install the Despia SDK

AF Events Reference

Full list of standard AppsFlyer events and parameters

In-App Events Overview

Revenue, currency, and deduplication rules

Support

Contact our support team

Deployment

Best Practices

Local Ecosystem

Analytics

Native Features

Roadblocks

Store Rejections

Platform Support

Lovable

​Installation

​Standard AF Events

​af_complete_registration

​af_login

​af_purchase

​af_start_trial

​af_subscribe

​af_add_to_cart

​af_initiated_checkout

​af_content_view

​af_search

​af_share

​af_invite

​af_tutorial_completion

​af_level_achieved

​Custom Events

​profile_created

​onboarding_step

​onboarding_complete

​subscription_start

​referral_sent

​streak_achieved

​content_viewed

​post_liked

​video_completed

​feature_used

​Frequently Asked Questions

​Resources

NPM Package

AF Events Reference

In-App Events Overview

Support

Installation

Standard AF Events

af_complete_registration

af_login

af_purchase

af_start_trial

af_subscribe

af_add_to_cart

af_initiated_checkout

af_content_view

af_search

af_share

af_invite

af_tutorial_completion

af_level_achieved

Custom Events

profile_created

onboarding_step

onboarding_complete

subscription_start

referral_sent

streak_achieved

content_viewed

post_liked

video_completed

feature_used

Frequently Asked Questions

Resources