> For the complete documentation index, see [llms.txt](https://help.craftsmanplus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.craftsmanplus.com/analytics/analytics-best-practices.md). # Analytics Best Practices How to Set Up Your PLAY Project for Clear, Actionable Data Your analytics are only as readable as the project structure behind them. In PLAY, two parts of analytics are directly affected by how you build your project: * [**Path View**](/analytics/analytics-dashboard/engaged/path-view.md) (scene flow): mirrors your project’s Path View in the editor. * [**Engagements by Layer**](/analytics/analytics-dashboard/engaged/engagements-by-layer.md): logs clicks/taps/presses against **layer names** (and aggregates identical names). This guide explains how to structure scenes and name layers so your analytics tell a clear story after export. ### 1. Keep the Path View Simple (use fewer scenes) {% hint style="info" %} **Rule of thumb:** If your Path View is easy to read in the editor, it’ll be easier to read in analytics too. {% endhint %} #### Recommendations * **Use as few scenes as possible.** If you can build an idea without adding a scene, do it. * Prefer **features that reduce scene sprawl** (for example: carousel components, show/hide layers, state changes) instead of building “UI” by chaining many scenes. * Avoid **complex looping scene graphs** (where scenes connect back to earlier scenes in multiple directions). These can become very hard to interpret in analytics. #### Why this matters Analytics Path View is a visual map of your scene network. Highly “webbed” or cyclical structures may still be valid creatively, but they make it harder to answer questions like: * “Where did users drop off?” * “Which branch performs best?” * “How often do users reach the end card?” ### 2. Name Scenes so the Path View can be Understood by Anyone Scene names appear directly in the Path View, so naming is part of making analytics readable. #### Good scene naming habits * Use names that describe **what the user is seeing/doing**, not internal shorthand. * If scenes are sequential, **number them** so the flow is obvious. * If scenes represent variants, include the variant label clearly. #### Example patterns * `01_Intro` * `02_Tutorial` * `03_Product_SelectColor` * `04_Result_Win` * `05_EndCard` #### Avoid * `Scene 2 - M3` (unclear to anyone who didn’t build it) * `Test`, `New Scene`, `Untitled` (not actionable in analytics) ### 3. Use Clean, Unique Layer Names [**Engagements by Layer**](/analytics/analytics-dashboard/engaged/engagements-by-layer.md) records interactions (like button clicks) against the **layer name**, and **layers with the same name are aggregated together**. That means layer naming can make the difference between: * “Users clicked *Swipe Right – Model 3* a total of 2,104 times”\ vs * “Users clicked *Hotspot* a total of 8,522 times” (but you can’t tell which model performed best) #### Best practices for layer naming * Give every interactive layer a **specific, descriptive name**. * If an interaction exists on multiple scenes but should be tracked separately, **make the layer name unique per context**. * If you *want* aggregation (e.g., one CTA used everywhere), use the same name across layers or use a [global layer](/play/layers/global-layers.md). {% hint style="info" %} **Need to refactor an existing project?** Ask Craftsman Intelligence to fix your layer names for you! {% endhint %} #### Recommended naming patterns **CTAs** * `CTA_Primary_Download` * `CTA_Secondary_LearnMore` * `Logo_Click` **Swipes / hotspots / choices** * `Hotspot_SwipeRight_Pizza1` * `Hotspot_SwipeRight_Pizza2` * `Hotspot_SwipeLeft_Pizza1` * `Btn_Choose_Blue` * `Btn_Choose_Red` **End card** * `EndCard_CTA_Download` * `EndCard_Close` {% hint style="info" %} #### Quick Rule If you’ll ever ask in a report, **“Which one performed best?”** then those “ones” need distinct layer names. {% endhint %} ### 4. Be aware: auto-advancing scenes can inflate scene completion If scenes automatically transition after a timer, scene completion percentages can look unusually high because users “complete” scenes without actively interacting. This isn’t necessarily wrong, auto-progression can be good for the experience, but it can affect how you interpret Path View percentages. **How to use this insight:** * Treat **scene completion** as “the user reached the next scene,” not always “the user engaged.” * Use [**Engagements by Layer**](/analytics/analytics-dashboard/engaged/engagements-by-layer.md) as your source of truth for interaction intent. ### 5) Pre-Export Checklist for “Analytics-Ready” Projects Before exporting your playable, do this quick audit: #### Path View * [ ] Can someone unfamiliar with the project understand the flow? * [ ] Are there unnecessary scenes you could merge/remove? * [ ] Are there complex loops that could be simplified (or replaced with features)? #### Scene Names * [ ] Do names describe what’s happening? * [ ] Are steps and variants clearly labeled? #### Layer Names * [ ] Are all interactive layers named clearly? * [ ] Are “repeated but different” interactions uniquely named (e.g., per model/card/option)? * [ ] Are “repeated and same” interactions consistently named (e.g., one CTA)? --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.craftsmanplus.com/analytics/analytics-best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.