Meta Ads Attribution (Conversions API)

Meta ads attribution sends your install and revenue conversions from Ranksy to your Meta pixel through the Conversions API. Meta can then optimize toward merchants who install and pay, rather than toward clicks.

The Conversions API solves a problem that is specific to Shopify apps. A merchant clicks your ad in the Facebook or Instagram in-app browser, then installs the app later in a different browser. The click context does not continue to the install, so Meta can miss the conversion. Ranksy sends the conversion from the server instead.

What You Need

• Shopify Partner API connected. Installs and revenue come from there. Without this connection, Ranksy has no conversions to send. See Connect Partner API.
• A Meta pixel (dataset) ID. Use the same pixel as your Shopify listing.
• An Events Manager access token for that pixel. Generate the token in Meta Events Manager under Settings → Conversions API → Generate access token.

Connect Your Pixel

1. Go to My Apps. Select your app. Click Settings.
2. Open the Meta Conversions API tab.
3. Enter your Pixel / Dataset ID and Access token.
4. Select a Revenue value:
   • Net (after Shopify fee) is the amount that you keep. This value is the default.
   • Gross is the full charge before the Shopify fee.
5. Click Save Configuration. Then click Test connection.

The tab shows a status badge and the time of the last event send. If a test fails, the tab shows the error message from Meta. Use that message to find and correct the cause.

💡 Ranksy stores the token encrypted. Ranksy never sends the token back to your browser. When you change the settings later, leave the token field blank to keep the existing one.

Check That Events Are Landing

A successful connection test only shows that your credentials are correct. To confirm that real conversions arrive:

1. Open Meta Events Manager. Select your dataset.
2. Look at the Overview tab for your event names. Lead and Purchase are the default names. Server events show a Server source.
3. Look at Event Match Quality for each event. This score shows whether Meta can connect your conversions to the people who saw your ads.

The events do not all arrive at the same time. Ranksy sends an install event as soon as it identifies the store. Revenue can take up to one hour to appear. The Disqualified and Invalid click events follow the rules in Exclude disqualified merchants and invalid clicks.

Use the Ranksy Ad Destination URL

After the connection, the tab shows a Meta ad destination URL. The URL has this form: apps.ranksyapp.com/your-app/abc123. Use this URL as the destination of your ad. Do not use the App Store link.

The URL does three things that a direct App Store link cannot do:

• It records the click on the server: IP address, browser, and the Meta click and pixel IDs. Ranksy attaches these signals to the conversion later. Meta uses the signals to match the conversion.
• It moves the visitor out of the in-app browser. Facebook and Instagram open links in their own webview. The redirect sends the visitor to the default browser of the device. The listing visit and the install then occur in one browser, and Ranksy can connect them.
• It passes your parameters through. Keep your ?utm_… tags on the URL. The tags continue to the Shopify listing.

Ranksy also records every ad click. You can then see how many clicks became installs. Shopify does not show this number.

Choose the Events You Send

Under Events sent to Meta, use the switch for each signal to turn it on or off. Select the Meta event for the signal. Value and currency come from your Partner API revenue. You do not type them.

Install and qualified install

When the Install signal maps to Lead, the store must pass each selected gate:

• Include only paid Shopify plans: a recognized paid Shopify plan passes. A development or test store fails. An exact Shopify Trial plan passes only when the store is strictly older than seven days at send time. A store that is exactly seven days old fails. A missing or future creation date also fails.
• Only fire for stores older than N days: the store creation date must be strictly older than N days. N can be 1 to 30. The default is 4.

The store must pass all selected gates. A higher minimum age also applies to an older trial store. For example, a store that is eight days old passes the seven-day trial exception but fails a store-age gate of fourteen days.

A recognized paid plan also passes when an old development flag is present. A development or test store fails Lead when the plan is not paid.

The Qualified install signal maps to CompleteRegistration by default. It sends only when the install stays installed for four days. Ranksy checks the live status at send time. A frozen, closed, or removed install does not send. This signal shows that the store stayed installed for four days. It does not prove that the merchant will stay.

Filter bot stores

Freshly created stores that install and stop are a common bot pattern. The Only fire for stores older than N days gate removes these stores. A large value prevents events from more bot stores. It can also delay the event past Meta's seven-day attribution window. The default value is 4.

Rename an event

If you change the Meta event for a signal, Meta can receive conversions from the last seven days one more time with the new name. Meta removes duplicates only inside the same event name. Events that Meta already received do not change.

Exclusion events

Ranksy sends two exclusion events: MerchantDisqualified and RanksyInvalidClick. Both are custom event names. Ranksy only sends the events. You apply the exclusions in Meta.

MerchantDisqualified

The Disqualified signal maps to MerchantDisqualified. Ranksy sends this event only when the store profile was fetched in the last seven days. The profile must show one of these conditions:

• The store has the Shopify development flag, or the plan is a recognized non-production plan.
• The plan is an exact Shopify Trial plan and the store is not reliably older than seven days.

An exact Shopify Trial plan is the plan that Shopify gives to a new store. It is not the same as an app subscription trial. An app subscription trial does not send MerchantDisqualified for the trial reason. The Trial started signal covers app subscription trials, and only apps that have trials show this signal. The manual is_test flag alone, an unknown plan, and the installation status do not send the event.

Ranksy sends one event for each store and reason. A recognized paid plan stops the event, even when an old development flag is still present.

RanksyInvalidClick

The Invalid click signal maps to RanksyInvalidClick. This signal is off by default. Turn on the signal in Events sent to Meta to send it.

Ranksy sends the event only for a live assessment with one of these verdicts:

• Invalid network: the network has abuse evidence and hosting or datacenter context, and it has Tor or proxy evidence.
• Invalid automation: the user agent is an automation client and the network has hosting, proxy, Tor, or abuse evidence.

Ranksy does not send the event for a known crawler. A VPN, a proxy, a country, a provider name, or a network risk score alone is not sufficient. A verdict does not prove fraud.

Ranksy sends the event only for a tracked click from the last seven days. The oldest hour of that window is not eligible, because Ranksy keeps a one-hour delivery margin. The click and the assessment must fall inside the remaining window. The click must have an fbc value, an IP address, and a user agent, and its provider lookup must occur within 24 hours. The 24-hour value is the freshness limit of the provider data. It is not a delivery delay.

When Ranksy checks a tracked click

When Ranksy stores a new tracked click, it queues an IP lookup. When Ranksy processes a qualified Lead, it also checks the click that Ranksy matched to the install:

• Ranksy keeps an existing assessment.
• If a stored lookup exists that is less than 24 hours old, Ranksy classifies the click with no new lookup.
• If no recent lookup exists, Ranksy queues the lookup and the delivery.
• A live invalid result queues the event delivery promptly.

A lookup failure does not stop a qualified Lead. A later backfill assessment never sends an event.

Exclude disqualified merchants and invalid clicks

To use the two events in Meta:

1. Confirm that Meta received the custom event and that the event is available for audience use.
2. Create an event-based audience in Meta where the event is available.
3. Apply the audience as an exclusion in your ad set.

Meta controls these steps, and the Meta interface can change. Ranksy only sends the events. Ranksy does not manage ad sets, audiences, IP lists, billing, or refunds. An invalid-click event never cancels a charge or starts a refund. Audience matching is not guaranteed. Meta decides the members of each audience.

How Merchants Get Matched

Ranksy sends each match signal that it has. Ranksy hashes the signals where Meta requires it:

• The identity of the store and the email of the merchant. A conversion can match even with no ad-click cookie.
• The owner name, phone, and location, where your Partner API data has them.
• The signals that Ranksy captured at click time, when the visit came through your Ranksy ad destination URL.

The click-time signals increase Event Match Quality. Meta optimization uses this score. Point your ads at the Ranksy URL to send these signals.

Troubleshooting

Revenue sends nothing. If the app has no paying merchants, the revenue signal has no events. The signal starts sending when the first charge arrives.

Status shows Error. Open the tab and read the message. The message is the rejection reason from Meta. Generate the access token again in Events Manager, save it, and test again.

Conversions arrive but match quality is low. Check that your live ads point at the Ranksy destination URL. Conversions from ads that link directly to the App Store have no click-time signals.

No event for a signal. Check that the switch for the signal is on. The Invalid click signal is off by default. Some signals apply only to apps with trials or subscriptions.

Turning it off. Disconnect Meta Conversions API at the bottom of the tab stops all events and clears your Pixel ID and token. You can connect again later with the credentials.

Related

• App Store Ads for keyword-level ROI on your Shopify App Store campaigns
• Traffic Hub for where installs come from, organic and paid
• Connect Partner API for the install and revenue source behind these events
• API reference for sending merchant details and events from your own code, which gives Meta more to match on