Preview Native Apps with Dynamic Content & Appetize.io

This lack of confidence can very quickly get out of hand with authors staying up late into the night to verify changes as they go live. Although being sleep deprived might lead to some creative content- there is a better way.

Dynamic Content solves this by making it easy to launch and embed your application at key stages in the production workflow, passing in contextual preview information so you can easily fetch and display the correct content (more on this later). When it comes to native IOS and Android apps, preview is often not supported by CMS tools or not seamless. The Dynamic Content approach to preview and versioning is designed to work with any technology, without forcing you to build your app drastically differently or use proprietary frameworks.

The final puzzle piece of a seamless native app preview is an emulator and in this guide we will be using Appetize.io. Emulators make it possible to load your app in the browser and CMS, removing the need to whip out 4 different mobile devices every time business users want to verify a change.

To show you how to use the preview feature we’ll walk you through a real example and explain how to set up your app in Appetize.io to render a preview that can be launched from Dynamic Content.

Concepts

Before we get started, let’s quickly recap the core concepts of adding preview into any application using Dynamic Content.

Virtual Staging Environments

Typically, your application will fetch content using the production content delivery API. To fetch work-in-progress content you can simply call the staging API instead.

If you want to preview a particular context, such as a point in time, a collection of changes or a specific version of a piece of content you can do that too. Our API automatically generates a unique URL for each preview context.

This makes it possible for every business user to preview their changes when they need to. We don’t think users should have to carefully coordinate changes into a single shared staging environment. It’s wasted overhead, creates a bottleneck and there is no guarantee what you see in staging is what you will get in production.

Preview

Preview lets business users launch your app from within the CMS with a pinned context. Users can see how the entire application will look at a point in time or with specific content in context.

1http://mysite.com/?stagingEnvironment={{vse.domain}}

You can register as many URLs as you like, including URLs pointing to your app emulator!

Visualization

Visualization on the other hand lets business users visualize an individual piece of content by embedding your app in the editing interface side by side. Dynamic Content tells your app which content item the user wants to view and your app fetches that content and renders it within the visualization pane of the content editing window.

It works the same way as preview, you provide a URL to your application with placeholders for contextual parameters to be passed in.

In addition to the staging environment URL, visualization passes in the id of the content item being previewed.

1http://mysite.com/cms-visualization?contentItemId={{content.sys.id}}&stagingEnvironment={{vse.domain}}

You can choose how best to display the content item. The most common approach is to create a visualization specific view that can fetch and display the content.

Getting Started

Let's get started by creating an Appetize.io account and uploading the app. For iOS apps you can upload a zip file containing the .app bundle and for Android upload the .apk file.

Configuring Preview

Next, we will integrate preview into the application. There are 3 simple steps required to achieve this.

1. Generate the embed URL, passing in the staging environment URL

2. Update your code to use the passed in staging environment URL to fetch content

3. Register the URL in Dynamic Content

Step 1 - Generate embed URL

Appetize.io has a handy tool to help construct the embed URL. Notice how it has a text box where you can supply a JSON dictionary of settings. This is where we will define the contextual parameters we want to pass from Dynamic Content to the app.

1{"stagingEnvironment": "{{vse.domain}}"}

1https://appetize.io/embed/YOUR_PUBLIC_KEY_HERE?device=nexus9&scale=100&autoplay=false&orientation=portrait&deviceColor=black¶ms=%7B%22stagingEnvironment%22%3A%20%22%7B%7Bvse.domain%7D%7D%22%7D

1https://appetize.io/embed/YOUR_PUBLIC_KEY_HERE?device=nexus9&scale=100&autoplay=false&orientation=portrait&deviceColor=black¶ms=%7B%22stagingEnvironment%22%3A%20%22**{{vse.domain}}**%22%7D

Step 2 - Update your code to use the new parameter

Next, we need to update the app to detect if the parameter was passed in and swap the URL that is used to fetch content.

iOS

Appetize.io adds the JSON properties into the UserDefaults on iOS.

1let stagingEnvironmentUrl = "https://" + UserDefaults.standard.string(forKey: "stagingEnvironment");

Android

In Android, the Appetize.io JSON properties are available from the intent.getExtras()) object.

1Bundle extras = getIntent().getExtras();
2
3if (extras != null && extras.containsKey("stagingEnvironment")) {
4
5String stagingEnvironmentUrl = "https://" + extras.getString("stagingEnvironment");
6
7// Use stagingEnvironmentUrl instead of production api
8
9}

Cross-platform frameworks

If you are using a cross-platform framework like Xamarin, React Native, Cordova or Ionic just look for the equivalent UserDefaults and Intent Extras APIs or plugins.

Step 3 - Register URL in Dynamic Content

Finally, we just need to take the embed URL from step 1 and add it to Dynamic Content.

Login to Dynamic Content, click the settings menu and go to “Preview”. Here you can add your embed URL and give the app a name, e.g. “iOS App”.

Configuring Visualization

In this section, we will build on top of the preview features you have already implemented to add support for visualization. This will let your business users see what content looks like before it is placed into a slot in the app, allowing review much earlier in the workflow.

Step 1 - Generate the embed URL

As with preview, we need to generate an emulator embed URL but we will include an extra parameter to pass in the content item id. An example embed URL is shown below.

1https://appetize.io/embed/YOUR_PUBLIC_KEY_HERE?device=nexus9&scale=100&autoplay=false&orientation=portrait&deviceColor=black¶ms=%7B%22stagingEnvironment%22%3A%20%22**{{vse.domain}}**%22%2C%20%22contentItemId%22%3A%20%22**{{content.sys.id}}**%22%7D

Step 2 - Create a screen to display the content

Next you need to create a view / activity / screen in your app which will fetch and display the content item. We need a special screen for this because the content item the author is working on may not appear anywhere else in the app.

You can implement this any way you choose; it could be a completely different view, or you could inject it into the app somewhere. We chose to insert a “Visualization” tab into our app’s tab bar. The tab fetches the content item and displays it using all the same components and views used elsewhere in the app.

Step 3 - Launch your visualization

We only want to show the visualization if the app is embedded in the content form. You should read in the new “contentItemId” parameter using UserDefaults / intent.getExtras() and if set, proceed to display your visualization.

Step 4 - Add URL to Content Types in Dynamic Content

Once you are happy with the result, you can register the embed URL in Dynamic Content. Unlike preview, visualizations are set at the content type level so you can provide different visualizations for different content types.

Simply open the content type you want to add a visualization to, add the visualization and hit save. Next time you open the content editor for that content type you will be able to choose to display the visualization.

Final thoughts

Adding preview and visualization to your apps makes a big difference to the day to day life of a content author. Dynamic Content makes implementing this as simple as swapping an API basepath and passing some parameters so you can focus on building awesome apps.

If you would like to learn more, be sure to check out the documentation for information on virtual staging, preview and visualization.