Menu
Menu Sheet Overlay
Search
Search Sheet

      Getting Started

      This guide contains everything you need to know to start developing with the Mobify Platform.

      Important: Our installation instructions have been updated to reflect many new technologies released starting in November 2018. If you need to install a project that was generated before November 2018, you can still access the old Quick Start guide for now.

      About the platform

      The Mobify Platform is a Front-end as a Service for ecommerce. It includes:

      • Software development kits (SDKs) to build shopping experiences using Progressive Web Apps (PWAs), Accelerated Mobile Pages (AMP pages), and native apps
      • A scalable application delivery network to deploy those experiences, plus a web portal to manage them
      • Integrations to simplify adding commerce, content management, and marketing techonology systems to the front-end
      • Analytics data to understand shoppers’ experiences

      Essential skills

      You’ll need intermediate knowledge of JavaScript to successfully onboard with the Mobify Platform. Before diving in, it’s a good time to get familiar with:

      • Writing modern JavaScript in ECMAScript 2015 (also known as ES6)
      • Using Node and Node Package Manager to install and manage JavaScript dependencies
      • Building React components to render user interfaces
      • Using version control systems like Git to store your code

      What kind of PWA are you creating?

      Depending on your project, there are two different approaches to creating a PWA using the Mobify Platform: tag-loaded and server-side rendered. While much of the setup is the same, some instructions will differ between the two types of projects. Throughout this guide, we’ll highlight when the instructions differ for the two types of projects. In other guides, sometimes the content will only be applicable to one type of project.

      Let’s compare the two types of projects…

      Tag-loaded projects

      If you’re building a PWA that renders only on the client-side, without making use of Mobify’s server-side rendering, you will be creating a tag-loaded project using the Mobify tag. The Mobify tag is a snippet of HTML and JavaScript that loads your PWA into an existing web page. This is typically used to give the PWA experience only to mobile users.

      If you’ve developed with the Mobify Platform in the past, you will likely be familiar with the process of developing tag-loaded PWAs.

      To learn more about tag-loaded PWAs, visit our Architecture overview.

      Server-side rendered projects

      What's a UPWA? In version 1.6 (Nov. 2018) of the Progressive Web SDK and earlier versions of our documentation, we referred to our server-side rendering technology as "Universal Progressive Web Apps" or "UPWAs." We’ve decided to stop using these names, so look for “server-side rendered” instead.

      If you’re developing a PWA that uses Mobify’s server-side rendering technology, then the site can work across any device, including desktop screens, mobile phones and tablets. This means you will not be needing the Mobify tag. In a server-side rendered PWA, your code will run on Mobify’s server and then again in the browser, unlike a tag-loaded PWA, which only ever runs and renders in the browser. Our server-side rendering technology was introduced to Mobify partners in late 2018.

      To learn more about server-side rendered PWAs, visit our Architecture overview.

      Installing the Mobify tag

      Important: These instructions are only required for tag-loaded PWA projects. If you’re working on a server-side rendered PWA, you can skip this because you will not need the Mobify tag. You can also skip this section if the Mobify tag has already been installed for you by a backend engineer or if you're working with our training-project repository.

      Before you can start development on a tag-loaded PWA, you, or someone on your team, will need to insert the Mobify tag into your site’s HTML.

      Mobify Cloud project

      Check that you have a project created for you in Mobify Cloud. If your project does not appear, contact Mobify Cloud support to make sure that the project has been created and that you have been granted access to it as a team member.

      After you have access to Mobify Cloud, make sure you can access your project-specific Mobify tag by logging in to Mobify Cloud, then clicking the Tag tab on the left-hand side navigation menu. This page provides you with the code you will need to add to your site’s HTML.

      Server access

      To complete the setup, you will need to change the HTML sent by your web server to include the Mobify tag. If you’re not sure how to do this, ask your site’s administrator for help.

      Deployment environments

      Send Mobify Support a list of any development, testing, and production environments. A Mobify tag with multiple environments in place will be set up accordingly on Mobify Cloud, allowing you to select a target environment to deploy bundles of code when you’re ready to publish. If you’d like to add new environments later, a new tag will need to be generated after Mobify adds the new target. We do not need to replace old tags that have already been installed.

      Steps to install the Mobify tag

      The installation process for the Mobify tag will be a bit different depending on your site’s ecommerce backend:

      If you’re working with a Salesforce Commerce backend, you can skip these steps because Mobify’s cartridge will install the Mobify tag for you. For more details, see Commerce Integrations

      If you’re working with an SAP Hybris backend, you can skip these steps because Mobify’s extensions for SAP Hybris will install the Mobify tag for you. For more details, see Commerce Integrations

      Add your project’s tag to the <head> tag of each page where you want to load the PWA:

      <!doctype>
      <html>
      <head>
          <title>Example Title</title>
          <meta name="title" content="Example Meta Title">
          <meta name="description" content="Example Meta Description">
      
          <!-- 📍 The tag goes here, early in the <head>, after SEO tags: -->
          <!-- MOBIFY -->
          <!-- ... -->
          <!-- END MOBIFY -->
      </head>
      <!-- ... -->
      </html>

      Verify that you placed the tag correctly by viewing the source of your pages and confirming that you see the tag within the HTML. Depending on your system, you may have to flush your cache, or rebuild pages for the tag to appear.

      The Mobify tag works best when it is placed:

      • Early in the <head> tag
      • Above any external resources like JavaScript or CSS files
      • Below SEO tags such as <title>, <meta name="title"> and
        <meta name="title">

      Installing the Mobify service worker

      Important: These instructions are only required for tag-loaded PWA projects. If you’re working on a server-side rendered PWA, you can skip the manual installation of your service worker. It will come pre-configured in your project! You can also skip this section if the service worker has already been installed for you by a backend engineer or if you're working with our training-project repository.

      Service workers are web browser features that provide PWAs with some of their app-like superpowers, including the ability to work offline and to be installed to users’ home screens, just like native apps. To realize the full potential of the Mobify Platform, tag-loaded PWAs will need to install the service worker (it comes pre-configured in server-side rendered projects). The installation steps will depend on your site’s ecommerce backend:

      If you’re working with a Salesforce Commerce backend, you can skip these steps because Mobify’s cartridge will install the Mobify service worker for you. For more details, see the cartridge section in Commerce Integrations.

      If you’re working with an SAP Hybris backend, you can skip these steps because Mobify’s extensions for SAP Hybris will install the Mobify service worker for you. For more details, see the extensions section in Commerce Integrations.

      Steps to install the worker:

      Installing the service worker (the worker, for short) requires serving a JavaScript file over HTTPS from the root of your domain. You can do this in three steps:

      1. Find the code for your worker in your project: packages/pwa/service-worker-loader.js. Copy its contents.
      2. On your server, create a worker file called service-worker-loader.js that is available from the root of your domain. For example, if your domain is example.com, the file must be example.com/service-worker-loader.js.
      3. Paste the worker’s code (from step one) into the file you just created.

      Steps to verify that the worker is installed correctly:

      1. Open your browser and navigate to the service worker over HTTPS. For example, if your domain is example.com, you would open https://example.com/service-worker-loader.js.
      2. Check the worker opens using HTTPS without errors. Service workers are powerful features that only work over secure connections.
      3. Check the worker is served exactly from the path /service-worker-loader.js without redirection. Redirects break the worker’s scope by changing the URL where it is registered.
      4. Check that the contents of the worker on your server exactly match the contents of the worker in your project.
      5. Check the worker is served using the Content Type application/javascript.

      You can see an example of a correctly installed worker by opening this URL in your web browser: https://www.merlinspotions.com/service-worker-loader.js

      Merlin's Potions worker is correctly installed

      Troubleshooting:

      If it’s not possible to install the service worker during development, workarounds are possible using Charles, an HTTP Proxy application.

      In production, the service worker must be installed correctly. To get help with installation during production, contact support@mobify.com.

      Installing required software

      Before you start development, you’ll need to install the following software on any computers you plan to use for development:

      Start by installing Node 8.10.0:

      • Go to the Node download page.
      • Download the right installer (a .msi file) for your machine. (For example, if you have a 64-bit machine, you would choose the x64 file.)
      • Run the installer and complete the setup instructions after downloading.
      • Open your command line interface (such as cmd.exe) and run node -v
      • Confirm that Node 8.10.0 has been installed successfully.

      For best results, do not use Node Version Manager (NVM) to install different versions of Node on Windows. In our testing, installations are more successful by installing Node directly without using NVM. (You can still use NVM to switch between versions of Node once they're installed.)

      Next, install Node Package Manager (NPM):

      • Open your command line interface (such as cmd.exe) and run the following command:
        C:\Users\yourFriendlyPC>npm install -g npm@5.7.1

      This command will take a few minutes to process without any output, but rest assured, the command is working in the background. Wait until you see the success message! Next, run `npm -v` to confirm that NPM 5.7.1 has been installed successfully.

      You will also need to install:

      Start by installing Node 8.10.0:

      • Go to the Node download page.
      • Download the installer for macOS (a .pkg file)
      • Run the installer and complete the setup instructions after downloading.
      • Open your terminal and run node -v
      • Confirm that Node 8.10.0 has been installed successfully.

      If you're using Node Version Manager (NVM) to install Node, then NPM 5.6.0 will automatically be installed for you. This version will be enough for your Mobify project. But if you want to take advantage of the npm ci command and are comfortable managing package-lock.json files, you can install NPM 5.7.1 to use these extra features. To install NPM 5.7.1, open your terminal and run npm install -g npm@5.7.1

      You will also need to install:

      Start by installing Node 8.10.0:

      • Go to the Node download page.
      • Download the right binary for your machine. (For example, if you have a 64-bit Intel machine, you would choose the x64 file.)
      • Extract the binaries and complete the setup instructions after downloading.
      • Open your terminal and run node -v
      • Confirm that Node 8.10.0 has been installed successfully.

      If you're using Node Version Manager (NVM) to install Node, then NPM 5.6.0 will automatically be installed for you. This version will be enough for your Mobify project. But if you want to take advantage of the npm ci command and are comfortable managing package-lock.json files, you can install NPM 5.7.1 to use these extra features. To install NPM 5.7.1, open your terminal and run npm install -g npm@5.7.1

      You will also need to install:

      Installing your project files

      Next, we’ll install a set of project files and get your development server running on your machine. If you’re working on multiple machines, you’ll want to run through these steps on each one.

      Cloning the training project

      Most of the time, the project files will already be generated for you, and you will need to ask someone from your team to give you access to them. If you’ve been given access to Mobify’s GitHub organization, you can download the files we use in our training courses using Git:

      #Clone the training project:
      $ git clone git@github.com:mobify/training-project.git
      #Change directories into the training project:
      $ cd training-project

      The training-project repository is private, so ask the Mobify team for help if you have trouble accessing it.

      Now that you have a project directory on your computer, let’s take a short tour of what’s inside. The most important directory in the project is packages. This is where you’ll spend most of your time in development. It contains all the code you’ll need to build a PWA, including multiple SDK packages from Mobify. Under the hood, we’re using Lerna to manage multiple packages in the same way React does.

      Installing dependencies

      Now we need to download and install package dependencies using Node Package Manager (NPM). From your root training project directory, run the following command:

      training-project$ npm install --quiet

      If you aren’t using the correct version of Node or NPM, the install command will fail, so make sure that you’ve installed the required software.

      It takes time to install all the dependencies. If you’re using Git Bash, it might take a few minutes before you see any activity in the terminal, so don’t cancel the process until it finishes. Thanks for your patience!

      Trusting the self-signed certificate

      Mobify PWAs use powerful features that don’t work on insecure origins, and the development server uses a self-signed certificate to allow it to serve pages over HTTPS.

      If you don’t trust the certificate on your machine, you will see HTTPS errors in your browser that will block you from doing local development.

      Here’s how to trust the certificate on different operating systems:

      1. Select Start Menu → Run and enter mmc.exe
      2. Select File → Add/Remove Snap-in
      3. Select Certificates and click Add
      4. Select Computer Account and click Next
      5. Select Local Computer and click Finish
      6. Click OK to close the Add or Remove Snap-Ins dialog
      7. Expand the Certificates node and right-click on the Trusted Root Certification Authorities node
      8. Select All Tasks → Import
      9. Import the localhost.p7b file in packages\pwa\dev-server. Leave all other settings as is while importing.
      10. After clicking Finish, you should get an alert saying “The import was successful”
      11. Exit the window. You do not need to save the console settings, so click No when prompted.
      1. Open your terminal and go to the packages/pwa directory inside your project directory
      2. Run open dev-server/localhost.pem. The Keychain Access app will now open.
      3. Add the certificate to your login keychain
      4. In the Keychain Access app, search for “Mobify Development Server”
      5. Right click it and select Get Info
      6. Expand the Trust section
      7. Set Secure Socket Layer (SSL) to Always Trust
      8. Close the info window. You will need to enter your password.

      Before previewing your project on Mobile Safari, the certificate needs to be accepted in the browser.

      1. Copy the address of the bundle location (for example, 192.168.0.1:8443/loader.js for LAN previewing)
      2. Open a new tab and go to the copied address
      3. A warning screen will appear saying “This Connection Is Not Private”
      4. Click Show Details
      5. Click Visit this website
      6. Confirm that the certificate has been accepted and that you access your project in the tab you opened previously
      1. Open a Bash terminal
      2. Go to the packages/pwa directory inside your project folder, and run the following commands:
      #Install libnss3-tools for managing certs:
      sudo apt-get install libnss3-tools
      #Initialize a database of certificates
      mkdir -p $HOME/.pki/nssdb
      #Pass in a password (default we’re doing below is no password)
      certutil -d $HOME/.pki/nssdb -N --empty-password
      #Add trust for the cert:
      certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n dev-server/localhost.pem -i dev-server/localhost.pem

      We recommend closing the terminal window and re-opening a new one to ensure your changes are applied.

      Running the development server

      Now we can start the development server for the PWA:

      Start by running the following commands:

      training-project$ cd packages/pwa
      training-project/packages/pwa$ npm run start:preview

      Now that the development server is running, you can open the PWA in a browser:

      1. Go to https://preview.mobify.com.
      2. Enter the URL for the site that you want to preview in the Site URL field
      3. Enter the URL for the code bundle you want to load in the Bundle Location field (This will usually be https://localhost:8443/loader.js).
      4. Emulate a mobile device in your browser. Here are some instructions for Google Chrome. Do not skip this step!
      5. Click Preview

      Success! You should now see the home page for the PWA in your browser. You can kill the development server at any time by using the keyboard shortcut Control-C.

      The site you want to preview must contain the Mobify tag, and you must emulate a mobile device in your browser before clicking the Preview button. Otherwise, previewing will fail. See the troubleshooting section for tag-loaded PWAs below for more help.

      Start by running the following commands:

      training-project$ cd packages/pwa
      training-project/packages/pwa$ npm start

      Now that the development server is running, you can open the PWA in a browser:

      Success! You should now see the home page for the PWA in your browser. You can kill the development server at any time by using the keyboard shortcut Control-C.

      Troubleshooting

      Windows users

      If you encounter errors in your terminal while starting your development server...

      Start by checking which version of Node is installed:

      1. Run node -v from your terminal
      2. Verify that the version is v8.10.0

      If you have a different version of Node installed, do not use NVM to install the newer version of Node. Instead, download the 8.10.0 release from the Node.js archive.

      Now reinstall your dependencies:

      1. Delete your node_modules directory
      2. Repeat the steps to run your development server and preview your work
      3. Don’t forget to check your Node version before running npm install again

      Mac users

      If you encounter errors in your terminal while starting your development server...

      1. Install Node Version Manager (NVM)
      2. Open your terminal and run nvm install 8.10.0
      3. Delete your node_modules directory
      4. Repeat the steps to run your development server and preview your work
      5. Don’t forget to check your Node version before running npm installagain

      Tag-loaded PWAs

      If you see a blank, white screen while loading...

      1. Clear your cookies for localhost and merlinspotions.com
      2. Go to the terminal window running your development server
      3. Press Control-C to stop the development server
      4. Run npm start
      5. Copy the preview URL from the terminal output
      6. Paste the URL into your browser
      7. Emulate a mobile device using your browser’s developer tools.
        You must do this before the next step!
      8. Click the Preview button

      If you see the desktop site instead of the PWA...

      1. Open Chrome’s DevTools
      2. Go to Application tab in the DevTools window
      3. Click the Clear site data button
      4. Verify that your local development server is running
      5. Copy the Preview URL from the terminal again
      6. Load the Preview URL (but don’t click the Preview button yet!)
      7. Emulate a mobile device using Chrome’s DevTools
      8. Click the Preview button

      If the PWA still doesn’t load...

      Start by verifying that the development server is running. You will know that your server is running when you see a message in your terminal window that states: “Server started ✓” with “Access URLs” listed below.

      If your development server is not running, ask yourself:

      • Did you run npm run start:preview from the packages/pwa directory?
      • Did the command fail because something else is running on the same port?
      • Did you click through your browser’s warning about the self-signed certificate?
      • Did you open the correct URL?

      Orientation exercises

      Now that your development server is up and running, it’s a great time to do some hands-on exercises to get the feel for Mobify PWA development. We recommend completing the two exercises below to make your first changes to the PWA and understand how it’s built.

      Adding a banner to the home page

      In this short tutorial, we’ll add a banner to the PWA home page, using the training-project package which you just installed.

      Open the file that renders the home page in your text editor:

      training-project/packages/pwa/app/pages/example-home/index.jsx

      Inside index.jsx, notice the ExampleHome React component. This component renders the content for the app.

      Let’s add a message to inform shoppers of a special free shipping promotion.

      To do that, add the following code within the render() function, below the <h1> tag:

      <h2>Free Shipping on orders over $50</h2>

      Save the file and refresh the PWA in your browser. You should now see your message!

      How it works: Behind the scenes, npm start watches for changes to your files and automatically rebuilds the PWA.

      Now it’s time to use our first component!

      Mobify’s PWA SDK comes with a library of React components, one of which is for creating a Banner. Let’s modify our code to replace the simple message we added above with the Banner component from SDK and take advantage of its enhanced styling.

      First, let’s import the base styles for the Banner component.

      Open the following file:

      training-project/packages/pwa/app/styles/themes/_pw-components.scss

      This file defines the styles for all the components that come from Mobify’s component library.

      Look for the comment // [AAA] Progressive Web SDK Base Styles, and add the following import statement below it:

      @import 'node_modules/progressive-web-sdk/dist/components/tile/base';
      + @import 'node_modules/progressive-web-sdk/dist/components/banner/base';

      Why do I need to import the styles? To keep the size of your CSS files down, you should only import the styles for the components you plan on using. That is why a freshly-generated project, which does not use the Banner component, does not already import the styles for the Banner component.

      Now go back to the index.jsx file for the home page.

      Let’s use the Banner component inside our ExampleHome component. We’ll need to import the component and add the Banner component inside the render function, like this:

        import ListTile from 'progressive-web-sdk/dist/components/list-tile'
      + import Banner from 'progressive-web-sdk/dist/components/banner'
      ...
        <h1 className="u-padding-top-md u-margin-bottom-sm">Home page</h1>
      - <h2>Free Shipping on orders over $50</h2>
      + <Banner icon="info" title="info">
      +   Free Shipping on orders over $50
      + </Banner>

      Save the file and refresh to see the new Banner.

      Styling the banner

      To create our own styles for the banner on top of the base SDK theme styles, we need to create a new file under training-project/packages/pwa/app/styles/themes/pw-components/ called _banner.scss.

      Let’s add some styles to _banner.scss:

      .pw-banner {
          background-color: $brand-color;
          color: $neutral-00;
      }

      Now go back to training-project/packages/pwa/app/styles/themes/_pw-components.scss. Look for the comment, // [BBB] Progressive Web SDK Custom Styles and add the following import statement below it:

      @import 'pw-components/banner';

      Reload, and you’ll see your banner with the new background color.

      Great work! You just learned how to customize your home page using your first SDK component! From here, you may want to explore some of the other components, by visiting our Component Library.

      Changing your project’s category list

      Mobify PWAs fetch and update data from ecommerce platforms using Mobify’s Commerce Integrations technology. Commerce Integrations provides an interface, called a connector, to make communicating with the backend easy.

      Let’s explore the connector that comes with your training project and change it to include another category. Imagine we’re launching a kid’s clothing line, and we want to include a Kids category in the menu.

      Start by opening the connector’s index.js file located at the following path:

      training-project/packages/connector/src/index.js

      Notice that the connector lives in a separate package from the PWA? This connector is special: it’s a mock implementation that does not actually fetch any data from a backend system. Instead, it loads product data directly from your local filesystem. This is great for local development because you can test any code that communicates with the backend without having to configure or test the backend itself!

      Eventually, you will want to implement a connector that does fetch data from your production backend, but for now, we’ll use the mock connector to show you how the connector works.

      To add a new category, open the categories.json file located at the following path:

      training-project/packages/connector/src/data/categories.json

      Now, let’s add a new category for “Kids.” In the categories.json file, look for the array of objects under the first categories key and add a new object to that array for the Kids category (the first object in the array is for the All category). Here’s what the new object should look like:

      {
          "id": "kids",
          "name": "Kids",
          "description": "Kids wear.",
          "categories": [
              {
                  "id": "kids-tshirts",
                  "name": "T-Shirts",
                  "description": "Kids T-Shirts."
              }
          ]
      }

      Double-check that the file is still valid JSON and that you didn’t include any trailing commas.

      Save the file and refresh the page. You should now see two categories in the menu: All and Kids.

      Great work! You’ve now got some hands-on experience working with the Mobify Platform.

      To learn more about the parts of the Mobify Platform and how they fit together, we recommend that everyone check out our Architecture overview.

      And if you’re the type of person who learns best by doing, you’ll find more hands-on material in our Guides.

      Recommended resources

      In this last section, we’ll introduce you to a few learning resources that can help you ramp up on the tools and technologies you’ll be using with the Mobify Platform. Grab a coffee, it’s time to get learning!

      Git and GitHub

      Even if you won’t be using Git and Github to manage your source code during development, you will need to use them if you plan on attending a training session with Mobify or if you need to review any of Mobify’s source code.

      JavaScript and ES6

      Most of the coding you’ll be doing with Mobify PWAs will be in JavaScript. You will be using many new language features included in the ECMAScript 2015 (ES6) standard.

      React and Redux

      We use these two foundational technologies to build user interface components and manage the flow of data in our applications.

      • React Github: a great starting place for React. Here, Facebook defines what React is and shows what their technology can do using simple code examples.
      • React Docs and React Tutorial: more in-depth resources from Facebook. Be aware that the tutorial can take a long time to complete, and it covers how to manually manage your application’s state—a task that is best left to Redux.
      • Redux Docs: official Redux documentation. The basics covers a simple to-do list application as an example of how the different parts of Redux work together.
      • Getting Started With Redux: this is a series of videos narrated by Dan Abramov, the creator of Redux. Abramov will walk you through the to-do list example from the official Redux Docs. As a caution, some of the videos may overwhelm junior developers as they explore different architectural approaches.
      • Redux Examples: a collection of simple examples that illustrate how React and Redux work together. Interactive versions of most examples are provided using CodeSandbox.
      • Redux Tutorial from François Bonnefont: teaches you the basics of React and Redux through annotated source code.
      • React-Redux Tutorial From Vincent Audebert: practice using React and Redux together with three different exercises. Good luck cheating: the author states that “solutions are encoded in base64 so you don’t get too tempted to look at them directly.”

      IN THIS ARTICLE: