Luseri / Guides
Which searches bring merchants to your Shopify app
Every time a merchant opens your listing from the App Store, Shopify adds where they came from to the address of the page: the words they searched for and the position your app held. If your listing is connected to Google Analytics 4, that information is already sitting in your property.
Updated
What Shopify adds to the address
| Parameter | What it tells you |
|---|---|
surface_type | The kind of page the merchant came from: search, search_ad (a paid placement in search), category, home, collection, story, partners, app_details (another app's listing) or app_group. |
surface_detail | For a search: the words the merchant typed. For a category: its name. |
surface_inter_position | For search and categories: the results page number. |
surface_intra_position | The position on that page, counted left to right, top to bottom, starting at 1. |
locale | The language the merchant uses in the App Store. It is absent for English. |
Set it up once
- In your Partner dashboard, open Apps, your app, Distribution, then Manage listing.
- In the Tracking information section, paste your GA4 measurement ID (it starts with
G-) in the Google Analytics code field and save. - To also receive confirmed installs, create a Measurement Protocol API secret in GA4 (Admin, Data streams, your stream) and paste it in the same section.
Google Analytics only starts counting from that day: there is no history before it.
Where to read it in GA4
In Explore, build a free-form report with the dimension Page path + query string and the metric Views, filtered on surface_type=search. Each row is one arrival, and the address contains the search term and both positions.
- A click on the Install button sends two events,
add_to_cartandAdd App button. They count the same click: use one, not their sum. - A completed install arrives as
shopify_app_install, sent by Shopify's servers. It has no page of its own, so use the dimension Landing page + query string to see which search the visit started from. - Results pages hold 24 apps, so the rank is (page − 1) × 24 + position.
What a real listing showed us
We read a live listing's property in October 2026. A few things were not obvious from the documentation:
- Only about one view in four carried a source. The others were direct arrivals on the listing, from a link or another site.
- In the Source / medium report, App Store visits appear as
(direct). The breakdown bysurface_typeis the only way to tell search from categories and ads. - Some visits came from results page 35. They are almost certainly robots, and they wreck an average position if you leave them in. We ignore positions beyond page 10.
- Most confirmed installs could be tied to a visit, and therefore to a search, through the landing page.
What this cannot tell you
You only see searches that ended in a visit to your listing, so a keyword where you rank on page three and nobody clicks stays invisible. You see nothing about competitors. And merchants who refuse analytics cookies are not counted, so real numbers are somewhat higher.
Luseri reads these addresses for you every day and turns them into a table: each search with its views, install clicks, confirmed installs and average position, filterable by country and language.
Questions
- Do I need custom dimensions in GA4?
- Not to read search terms and positions: they are in the page address. Custom dimensions are only needed if you want the parameters of Shopify's server-side events, such as the store behind an install.
- Why does my position look better than I expected?
- Because it is measured when someone clicks. A listing far down the results is rarely opened, so the positions you see lean toward the good ones.
- How far back does the data go?
- To the day you added your measurement ID to the listing. Luseri copies up to a year on the first reading.