Events - Despia Documentation

Events fired from your web layer are intercepted natively and logged through the AppsFlyer SDK in real time. Standard af_ prefixed events map automatically 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, lowercase alphanumeric characters and underscores only. There is a limit of 300 unique event names per day.

Installation

Bundle
CDN

npm install despia-native

pnpm add despia-native

yarn add despia-native

import despia from 'despia-native';

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

<script type="module">
    import despia from 'https://cdn.jsdelivr.net/npm/despia-native/+esm'
</script>

The log_event command

Fire any in-app event by passing an event name and a URI-encoded JSON object of values. Pass {} when there are no values.

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

event_name

string

required

A standard af_* event or your own custom name. Lowercase alphanumeric and underscores only, case-sensitive.

event_values

string

required

A URL-encoded JSON object of event parameters. Wrap with encodeURIComponent(JSON.stringify(...)). Keep values flat: strings, numbers, and booleans.

Standard AF Events

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

Event	When to log it	Maps to
`af_complete_registration`	Account created	Meta `CompleteRegistration`, TikTok `CompleteRegistration`
`af_login`	User logs in	Login
`af_purchase`	Payment completed	Meta `Purchase`, TikTok `CompletePayment`
`af_start_trial`	Free trial started	Meta `StartTrial`, TikTok `Subscribe`
`af_subscribe`	Paid subscription started	Meta `Subscribe`, TikTok `Subscribe`
`af_add_to_cart`	Item added to cart	Meta `AddToCart`, TikTok `AddToCart`
`af_initiated_checkout`	Checkout started	Meta `InitiateCheckout`, TikTok `InitiateCheckout`
`af_content_view`	Product or content page viewed	Meta `ViewContent`, TikTok `ViewContent`
`af_search`	Search performed	Meta `Search`, TikTok `Search`
`af_share`	Content shared	AppsFlyer only
`af_invite`	Invite or referral sent	AppsFlyer only
`af_tutorial_completion`	Onboarding or tutorial finished	Meta `CompleteTutorial`
`af_level_achieved`	Progression milestone	Meta `AchieveLevel`, TikTok `AchieveLevel`

af_complete_registration

Records when a user completes sign up.

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. 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. 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, used for deduplication.

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

af_start_trial

Records the start of a free trial.

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. 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.

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. Add 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.

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.

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.

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.

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.

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.

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

Custom events do not map to Meta or TikTok automatically, but appear in your AppsFlyer dashboard for funnel and retention analysis. Name them using lowercase alphanumeric characters and underscores, and keep the parameter set stable so dashboards stay queryable.

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

A few more examples, each fired the same way:

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

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

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

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

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

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

To postback a custom event to Meta or TikTok, map it manually in Configuration > Integrated Partners > [Partner] > In-App Events. Standard af_ events are mapped automatically.

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 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)))

Do events work offline?

Yes. The native SDK queues events on the device and sends them when connectivity returns.

Do I need to identify the user first?

No, but events logged after set_user_id are tied to your internal user ID in raw-data exports. Identify as early as you can, see User Identity.

Resources

NPM Package

despia-native

Support

support@despia.com

​Installation

​The log_event command

​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

​Frequently Asked Questions

​Resources

NPM Package

Support

Installation

The log_event command

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

Frequently Asked Questions

Resources