Add a widget to an asset

You can add up to three widgets to an asset through the Magine Pro Console which will show up on the web and the mobile apps. You can decide which widgets are highlighted when a user is entering the page of the asset. The About tab will always go first but you can define the order of the widgets by drag and drop. Remember to save your changes when you are done.

If you would like to enrich an asset with widgets do the following:

1. Login to the Magine Pro Console
2. Find the asset in the metadata section
3. Select the asset and click on the Widgets tab
4. Click add and edit the settings of your web view
5. Save your changes

Web view settings

• Title: Used to name the tab in the app. Use max 13 characters so that the title is also shown correctly on mobile screens.
• URL: The URL to the page you want to add as a widget
• The URL supports two types of Query Strings to enchance the response of the web server:
• [userID] - If the user is logged in, it will pass the userID as a parameter in the URL
• [contentID] - It will pass the assetID as a parameter in the URL
• For example: https://www.maginepro.com?variableA=[userID]&variableB=[contentID]
• For a logged in user, the client application will submit a GET request with the following URL https://www.maginepro.com?variableA=E6YGC467YHNZP9BIKK4RVNDLYUSR&variableB=83d8c055-e94a-41c1-b9ce-f3eab6de4a81
• The web server hosting the URL can then extract these parameter values and use them to personalise the response.
• In the example above, variableA and variableB are just examples, these can be replaced by any key you need, i.e. user=[userID]
• For a logged out user the response will be user=[userID]so the web application must handle this parameter.
• Allow navigation: Allows users on mobile devices to navigate back and forth inside the embedded page with the device controls.
• Height: The settings will decide in which height your web view will be rendered. It should match the height of your widgets page.
• Default: Decide if this widget should be displayed when a user visits the page
• HTML target="_blank" behaviour: If your HTML web-app uses this behviour in links, the following behaviour will occur:
• Web - Open a new tab in the existing browser
• Android - Open a new tab in the default browser
• iOS - Open a new tab in Safari

Add a widget to several assets at once

If you want to add one widget to several assets you can bulk edit them from the Magine Pro Console metadata section.

1. Mark the assets that you want to enhance with your widget
2. Click on bulk edit
3. Select "Add widget" and follow the steps in the dialogue window
4. Then click on update

Best practice: Implementation of widgets

Implementing widgets into native mobile apps and/or web requires some compliance and specific page code adaptations. We have listed below some known restrictions so you can provide the best experience to your end-users.

• iOS Webview Guidelines: https://webkit.org/
• Android Webview Guidlines: https://developer.android.com/develop/ui/views/layout/webapps

General UX aspects

• Remove extra web UI that doesn't apply to your app (header title, navigation menu, footer, etc). This will help to give the impression that the widget is part of the app or website.
• Remove external links so the app doesn't refresh the widget with external web content.
• Offer a way for the user to reload the page and clearly indicate the page is loading.
• Avoid context history for UX. As the web app consumes a lot of RAM, iOS/Android OS ends activity when it goes into the background. So the user might lose the page they were on or lost the form/game they filled in when launching the app again.
• Create a responsive view that properly adapts to all Platform. As the same widget is used on the web, iOS, Android, make sure the height match with all platforms. iOS and Android detect and apply page height, but not the web. You can define the height from the Magine Pro console instead.
• Do not allow file download

Code specifics

• See Apple & Android Developer Guidelines for specific requirements.
• Use recent SSL certificate or iOS won't load the page
• On iOS handle target="_blank" by webView (_:createWebViewWith:for:windowFeatures:)
• Android only supports GET. When POSTing a form, the handler is not called
• If you use a responsive widget, include the website template param in every web app links (eg. mobile=true at the end of URL)
• Try to prevent as much as possible advanced Javascript features
• Do not allow non-HTTP protocols such as mailto:
• There is no default way to display errors. If connectivity failure occurs no page is displayed or an error page is loaded.