Using Portals in Android
Once you obtain an API key and install Ionic Portals, you can start creating Portals for your application.
#
Creating a Custom Application ClassIn Android, you will have to register your Portals instance and start creating Portals via the PortalManager. To do this, a custom Application class is recommended. In this Application class, you can override Application#onCreate()
to register and create Portals.
- Kotlin
- Java
class MyApplication : Application() { override fun onCreate(): Unit { super.onCreate() PortalManager.register("MY_API_KEY") // setup portals }}
public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); PortalManager.register("MY_API_KEY"); // setup portals }}
caution
Avoid committing your Portals key to source code repositories where it may be publicly visible!
After creating a custom Application class, be sure to add the android:name
attribute to your application
tag in the AndroidManifest.xml
.
<?xml version="1.0" encoding="utf-8"?><manifest xmlns:android="http://schemas.android.com/apk/res/android" package="org.example.my.app">
<application android:name=".MyApplication" android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name"> /* ... */ /* other manifest code here */ /* ... */ </application></manifest>
#
Creating a Portal via PortalManagerAfter registering via the PortalManager.register() function, you can create Portals. Use the PortalManager to quickly create a Portal and link it to an XML layout.
- Kotlin
- Java
class MyApplication : Application() { override fun onCreate(): Unit { super.onCreate() PortalManager.register("MY_API_KEY")
val portalId = "MY_FIRST_PORTAL" PortalManager.newPortal(portalId).create() }}
public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); PortalManager.register("MY_API_KEY");
String portalId = "MY_FIRST_PORTAL"; PortalManager.newPortal(portalId).create(); }}
Now, the Portal is successfully created and managed by the PortalManager.
#
Linking the Portal in a Layout FileOne way to use Portals in android is directly in an XML layout file. Use the portalId
attribute in the XML tag as shown below to link it to the Portal you created.
<?xml version="1.0" encoding="utf-8"?><io.ionic.portals.PortalView app:portalId="MY_FIRST_PORTAL" android:layout_width="match_parent" android:layout_height="match_parent"/>
The strings.xml
resources file can be used to ensure the Portal ids match up, but it isn't necessary to do so.
#
Using a Portal in CodeAnother way to use Portals in Android is to inflate a PortalFragment with a Portal into a view. This method may be preferred if using a Portal in a ViewPager or a more dynamic UI structure. The following trivial example shows how to inflate a PortalFragment into an existing FrameLayout.
<?xml version="1.0" encoding="utf-8"?><RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools" android:layout_width="match_parent" android:layout_height="match_parent">
<FrameLayout android:id="@+id/my_portal_space" android:layout_width="match_parent" android:layout_height="match_parent"/>
</RelativeLayout>
- Kotlin
- Java
class MyContainerFragment : Fragment() {
override fun onCreateView( inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle? ): View? { return inflater.inflate(R.layout.fragment_container, container, false) }
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState)
val myFirstPortal = getPortal("MY_FIRST_PORTAL") val portalFragment = PortalFragment(myFirstPortal)
val fragmentManager: FragmentManager = childFragmentManager fragmentManager.beginTransaction().replace(R.id.my_portal_space, portalFragment).commit() }}
public class MyContainerFragment extends Fragment {
@Override public View onCreateView(@NonNull @NotNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) { return inflater.inflate(R.layout.fragment_container, container, false); }
@Override public void onCreate(@Nullable Bundle savedInstanceState) { super.onCreate(savedInstanceState);
Portal myFirstPortal = PortalManager.getPortal("MY_FIRST_PORTAL"); PortalFragment portalFragment = new PortalFragment(myFirstPortal);
final FragmentManager fragmentManager = getChildFragmentManager(); fragmentManager.beginTransaction().replace(R.id.my_portal_space, portalFragment).commit(); }}
#
Preparing the Containing ActivityConfiguration changes in Android can cause WebViews to restart within an Activity. We recommend adding the following line of code in your application AndroidManifest.xml
file for any Activity that will contain a Portal.
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
For example:
<activity android:name=".MainActivity" android:label="MyExampleApp" android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter></activity>
#
Preparing the Gradle Build FileSome web assets can contain directories that start with special characters like an underscore, but by default Android will omit these from your built app. Override the default Android settings by adding the following snippet in the defaultConfig
section of your module build.gradle
file.
aaptOptions { // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps. // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61 ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'}
For example:
android { compileSdkVersion rootProject.ext.compileSdkVersion defaultConfig { applicationId "com.myawesomecompany" minSdkVersion rootProject.ext.minSdkVersion targetSdkVersion rootProject.ext.targetSdkVersion versionCode 1 versionName "1.0" testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner" aaptOptions { // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps. // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61 ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~' } }
...}
#
Adding Web CodeNow that your Portal is successfully registered, created, and linked, you need to add the web assets to your application. The web code lives in folders under src/main/assets
. You can use either many web applications or one "Single Page Application" (SPA) and dynamically link to the route you want to use. By default, the PortalManager will look in the folder named the same as the portalId
used. You can use the setStartDir() function to set the web application's directory.
For more information on how to setup your web bundle, see our how-to guide on how to pull in a web bundle.