What is an Expansion Pack?

Expansion Packs provide a mechanism to deliver content to your app based on user selection. Consider an app that contains information relating to cars, trucks, and motorcycles. The total available data for the app might be quite large. However a single user might only be interested in content that relates to cars.

With expansion packs, you can configure the app to not contain any data when it is first installed. The user will be presented with an option to choose which category of content to download (cars, trucks, or motorcycles). Only after the user makes the selection is the content - or "expansion pack" downloaded to the device and made available in the app. 

How to enable expansion packs

To use Expansion Packs within an app, the "Expansion Pack Plugin" must be added to an app in the Plugins section. Underneath the block tree in the left side of the builder, select "Manage Plugins". From there, click the "Add Plugin" icon towards the top of the screen. In the pop up, select "Expansion Packs" and click the add button. 

On the Edit App screen, in the General tab, find the "Expansion Packs" section. By default, the "Expansion Pack Filter Field" will be blank. By filling in this field, you are enabling expansion packs for the app. 

The value you enter in the field should be the name of a column in at least one of your datasources. In the example of cars, trucks, and motorcycles, it would be something like "Auto Type". 

How the data is filtered

Only local datasources backed by a cloud collection will be filtered. A datasource will be filtered only if it has a column with the same name as the value you entered for "Expansion Pack Filter Field". So in the example above, the datasources that will be filtered all have a column called "Auto Type". Any other datasources will not be filtered. 

The filter value can only contain letters, numbers, and underscores. Only alphanumeric characters in the ascii table can be used.

How to configure your data source

After you have associated the data source to the app, hovering over the name of the data source below your views and block tree should reveal a link to the "Edit App-Data Update Property" page. Here, it is necessary to set the field for "Include data with build" to 'Yes' and "Hosted" set to 'No', otherwise you will see an error. Leaving the default settings as they are should avoid any issue.

Added app level Events

The expansion pack will add 4 app level Events:

1. expansionPackDownloadExists: This event will trigger if the Download Expansion Pack action is called, but the pack already exists
2. expansionPackDownloadStart: This event will trigger when downloading has been started

3. expansionPackDownloadProgress: This event will trigger repeatedly as the expansion pack downloads allowing the the production of UI elements that report download progress to the user

4. expansionPackDownloadSuccess: This event will trigger after download of the expansion pack has been successful
5. expansionPackDownloadFailure: This event will trigger for any errors that occur for download

How to configure the action

There is a new action created for downloading Expansion Packs. The action is called "Download Expansion Pack". On Android we can download simultaneous expansion packs, however, each expansion pack download must be unique, so this means you can't download 2 English packs.

The action will have 2 fields:
1. Filter Value: This will be the filter value for the expansion pack to download. For example, en or fr.
2. Expansion Pack Status Variable Name: A variable with this name will be set to the Filter Value whenever expansionPackDownloadExists, expansionPackDownloadStart, expansionPackDownloadProgress, and expansionPackDownloadSuccess get triggered. When expansionPackDownloadFailure is triggered then an error message will be set as the value. For example, if the Expansion Pack Status Key is set as "statusKey", and the filter value is "en", then whenever the expansionPackDownloadStart event is triggered, the [[var:statusKey]] will return a value of "en".
3. Expansion Pack Total Size Variable Name: A variable with this name will be set to the total size in bytes of the expansion pack we are currently downloading.
 4. Expansion Pack Progress Variable Name: A variable with this name will bet set to the number of bytes received so far for the expansion pack we are currently downloading.

Note: The expansion pack will be downloaded and stored on the device's internal storage.  

What the user will see

When the user opens the app, they will be prompted to select which type of content they wish to see. If they click on the button that says "cars", then only the content that relates to cars (i.e., only the content for which the column "Auto Type" contains the value "cars") will be downloaded. They can then use the app to browse the content that relates to cars. 

At a later date, the user might decide to view the content that relates to motorcycles. If they click on the button that says "motorcycles", separate content will be downloaded for motorcycles. The user can now use the app to browse content that relates to both cars and motorcycles. 

Important overall notes

1. In an app you can use Expansion Packs OR Content Distribution, but you CANNOT use both together within an app.
2. When an app is upgraded, existing Expansion Packs will be deleted from the app and a user will need to redownload the Expansion Packs again.
3. Expansion Packs downloads and compatibility will be based off the Original Installed Build version of the app, regardless of Quick Updates.