Skip to main content

Running JavaScript in the App

When CSS isn't enough - you need to remove elements, change text or links, or turn off website-only behavior - run your own JavaScript when the page is opened inside the mobile app. For simple hiding and restyling, prefer CSS.

There are two ways to run app-only JavaScript. Pick one for each piece of code - don't combine them.

App-only script (recommended)Inline script with the ready event
Where the code livesIts own file, e.g. assets/evlop-app.jsInline in your theme's Liquid files
Loaded on the websiteNo - never downloadedYes - but the code inside the listener never runs
How you write the codePlain code at the top level of the fileWrapped in an evlop-mobile-app:ready listener
Good forMost app-only code, and third-party scripts that should only run in the appA few lines tied to a specific section or snippet
Don't mix the two

App-only scripts are loaded after the evlop-mobile-app:ready event has fired. If you add an evlop-mobile-app:ready listener inside an app-only script, it will never run. Inline code, on the other hand, runs on the website too unless it's inside the listener.

Option 1: App-only script​

Load a whole script file only when the page is opened in the mobile app. On the regular website, the script is never downloaded or run.

The script tag​

Add a <script> tag with type="text/javascript+evlop-mobile-app" and put the script's URL in data-src (not src):

<script type="text/javascript+evlop-mobile-app" data-id="my-store-app-tweaks" data-src="https://example.com/my-app-tweaks.js"></script>
  • Browsers don't run scripts with an unknown type, so on the regular website this tag does nothing.
  • Inside the app, the SDK turns the tag into a normal script with src set to your data-src and loads it.
  • data-id is optional, but give each tag a unique id prefixed with something specific to your store, such as my-store-app-tweaks.

data-src can point to any script - a file from your theme's assets, or an external script such as an analytics or widget library that should only run in the app.

Setting it up with a theme asset and a snippet​

1. Create the script asset. In your Shopify admin, go to Online Store → Themes → ⋯ → Edit code, and add a new file under Assets named evlop-app.js:

assets/evlop-app.js
// this file is only loaded inside the mobile app - put your code at the top level

2. Create a snippet that includes it. Add a new file under Snippets named evlop-app-scripts.liquid:

snippets/evlop-app-scripts.liquid
<script
  type="text/javascript+evlop-mobile-app"
  data-id="my-store-app-tweaks"
  data-src="{{ 'evlop-app.js' | asset_url }}"
></script>

{%- comment -%} external scripts work the same way {%- endcomment -%}
<script
  type="text/javascript+evlop-mobile-app"
  data-id="my-store-app-widget"
  data-src="https://example.com/widget.js"
></script>

{%- comment -%} app-only stylesheets can go in the same snippet {%- endcomment -%}
<link rel="stylesheet+evlop-mobile-app" data-href="{{ 'evlop-app.css' | asset_url }}">

The asset_url filter gives the file's CDN URL, including a version parameter so the app picks up your changes when you edit the file. See Loading an app-only stylesheet for the <link> tag.

3. Render the snippet in your layout. Open layout/theme.liquid and render the snippet just before </body>:

layout/theme.liquid
    {% render 'evlop-app-scripts' %}
  </body>
</html>

Writing the script​

App-only scripts run after the SDK has finished setting up the page:

  • The DOM is fully parsed, and the evlop-mobile-app-embed class is already on <body>.
  • The evlop-mobile-app:ready event has already fired - put your code at the top level of the file and it runs right away.
  • The script only ever runs inside the app, so there's no need to check whether you're in the app.
note
  • The tag must be part of the page's HTML (for example rendered by Liquid, as above). Tags added to the page later by JavaScript are not picked up.
  • Scripts are loaded asynchronously, so if you add several tags, they may run in any order. Don't make one app-only script depend on another.

Option 2: Inline script with the ready event​

When the SDK has finished setting up the page inside the app, it dispatches an evlop-mobile-app:ready event on document. At that point the DOM is fully parsed and the SDK has already hidden the theme header and footer. The event is never dispatched on the regular website, so anything inside the listener is automatically app-only.

<script>
  document.addEventListener('evlop-mobile-app:ready', function () {
    // this code only runs inside the mobile app
  });
</script>

Add the <script> to layout/theme.liquid (just before </body>), to the section or snippet the code relates to, or - for one-off pages - to a Custom Liquid section in the theme editor.

No flicker

While the SDK is initializing, the page is covered by a white loading overlay. The overlay is removed in the same tick that evlop-mobile-app:ready fires, so changes you make synchronously in your listener are applied before the customer sees the page.

For worked examples, see Common Use Cases. They're written for an app-only script - to use one inline instead, wrap it in an evlop-mobile-app:ready listener.