bubbleHacks
bubbleHacks

Documentation | Henry Native Wrapper

Documentation

Setup in less than 5 minutes! Henry is a native wrapping technology that allows you to wrap your Bubble app using Thunkable while giving you access to advanced native features directly from Bubble.

Setup

👉
See Get Henry

Native features

💡
To use Henry’s native features, you will need to install the Henry | Native Features Bubble plugin to you Bubble app.
💡
When using Henry plugin elements on your page, please make sure they are visible on page load and not in any groups that are hidden. Otherwise they will not work properly.

Device

‣
Get device infos
  1. Place the ‘Henry: Device info’ element on the page
  2. On page load, the element will fetch the current device infos. You can use the element’s states to access it from other elements of workflows. Possible states are
    • Theme: light, dark
    • Operating system: iOS, android
      • image

Advanced

You can also update the device infos by using the ‘Update device info’ action in a workflow. This is useful to check if the user changed the theme during the session. Updating the device infos will also trigger an event ‘Device info is updated’ that you can use to attach some actions. ⚠️ The event refers to the update workflow being used, not the device infos changing.

image
‣
Get current location
  1. Place the ‘Henry: Location’ element on the page
  2. By default, the element will fetch the user’s current location on page load. You can use the element’s states to access it from other elements of workflows.
    3. image

    You can use Bubble’s Calculate formula → Coordinates to Address to convert the element’s output coordinates (latitude + longitude) into an address)

    image
    image

Advanced

You can manually deactivate fetching the location on page load by unchecking the element’s checkbox ‘Update location on page load’.

image

You can update the current location by using the ‘Update current location’ action in a workflow. This is useful if you unchecked ‘Update location on page load’ or the user moves during a session. Updating the location will also trigger an event ‘Location is updated’ that you can use to attach some actions. ⚠️ The event refers to the update workflow being used, not the location changing.

image
‣
Adjust the status bar and iPhone Notch Area

Show / hide the phone’s statusbar contents

You can show / hide the phone’s statusbar contents. This refers just to the contents of the status bar, not the bar itself.

  • Use the workflow action ‘Henry: Show statusbar contents’ to show the phone’s statusbar contents (default).
  • Use the workflow action ‘Henry: Hide statusbar contents’ to hide the phone’s status bar.

Set statusbar contents style

Use the workflow action ‘Henry: Set statusbar content style’ to set the style of the statusbar contents. Available options are

  • light-content: light text and icons
  • dark-content: dark text and icons
  • default: the phone’s current default

Set statusbar background color

Use the workflow action ‘Henry: Set statusbar color’ to set the background color of the status bar. For newer iPhones, the color will be applied to the whole ‘notch area’, which includes the status bar on the top as well as the small area on the bottom → green parts in image below.

💡
Apple devices: By default, the webview is contained to the save zone of the screen. This is the area between to top and bottom notch-areas (”safe-area-insets”). By default, setting the color or the status bar will also apply the same color to bottom notch-area. The color of the top and bottom notch areas on iOS cannot be set independently with Henry.
image

Henry currently has two ways to deal with that

1) (recommended) You can use the ‘Henry: Set iOS full screen’ workflow function to adjust the size of the web view for iPhones to cover the full screen including the notch areas.

Set to full screen

image

Reset to normal (contain webview to save area)

image

2) (not recommended) You can use the ‘Henry: Set webview height’ workflow function to adjust the size of the web view for iPhones to cover to bottom Notch area. This essentially hides the bottom notch-area on iPhones. For most iPhones, increasing the size by 34px will be best.:

image

image
‣
Save local (offline) variables

Henry allows you to save local (i.e. offline) variable directly on the users phone. This can be useful for

  • Sensitive data you don’t want to save in Bubble’s database hosted on AWS.
  • As an alternative to custom states that survive a refresh of the page and are available across pages. This is faster than writing something to the database.
  • Save the users login credentials. This way you can automatically log the user in when first opening the app and save the credentials offline. So, the user never has to create an account but still has a personalised experience.

At the moment Henry only supports 3 variables of type text. Here is how it works:

  1. Place the ‘Henry: Local variables’ element on the page
  2. Use the ‘Store local variable’ workflow action to store a text value in a variable.
    3. image
  3. On page load, the element will fetch the local variables. You can use the element’s states to access them anytime from other elements of workflows.
    4. image

⚠️. Although the plugin allows you to store some variables offline, but you will still need an internet connection to run the app.

Interaction

‣
Display alerts
  1. Place the ‘Henry: Alerts’ element on the page
  2. Use the ‘Show alert’ workflow action to display an alert. The Event ‘Alert ID’ is used if you want to catch if the user confirmed the alert (i.e. clicks ‘confirm’)
    3. image
  3. If the user confirms or cancels the alert, an event ‘Alert is confirmed by user’ resp. ‘Alert is cancelled by user’ is triggered. You can use this event to create a workflow. E.g. if user confirms event with Event ID ‘alert 1’, do something.
    4. image
‣
Vibrate

Use the workflow action ‘Henry: Vibrate’ to make the phone vibrate.

image
‣
Push notifications
💡
Unfortunately setting up and testing push notifications requires us to set up some stuff in the background, which for Apple can seem a bit daunting. But don’t worry, the process is pretty straight forward and we will guide you through all the necessary steps (+videos are coming soon!). Its also worth noting: On Apple devices you won’t be able to test the push notifications feature on your installed demo app, but you will need to upload the app to AppStore Connect and install it to your phone via TestFlight (we will walk you through this below).
💡
Please also note: To download or publish an app with the push notification component in Thunkable you will need a Thunkable pro subscription. See Thunkable docs → Push notifications.

Here is how to set it up:

‣
1. Preparation (Apple + Android)
  1. Make sure you are using the IAP & Push version of the Henry Thunkable template
  2. Add the ‘Henry: Push Notifcations’ element to your app.
  3. Create a free https://onesignal.com/ account (don’t set up any app yet), by following the steps outlined in Thunkable docs → Sign up with OneSignal.
  4. Install any OneSignal Bubble Plugin to your app. We recommend this free one here: https://bubble.io/plugin/onesignal-1550111582496x405806558737334300.
💡
Henry’s push notification features is currently in beta and only works in combination with other 3rd party OneSignal plugins for Bubble. We are currently working on extending the Henry | Push Notifications plugin so it can be used stand alone without other 3rd party plugins.
‣
2. Setup Android

This is pretty straight forward and should only take about 5 minutes. Follow the steps outlined in Thunkable docs → Android Setup. In summary, you will need to:

  1. Set up and configure a Firebase account
  2. Configure Android settings in your OneSignal account and link your Firebase Keys
  3. Add your OneSignal Key to Thunkable

Please note:

  • You can ignore Step 5. Toggle Location Permission.
  • In Step 4. Install Your SDK you find the Push Notifications dialog to add your App ID by clicking on the Push_Notification 1 element just below the phone (see picture below → bottom right)
    • image

💡
After the setup, please make sure to re-download or republish your app for the changes to be effective.
‣
3. Setup Apple
💡
Please note that to test push notifications on iOS you will need to send a build of your app to your AppStore Connect account and download your app to your phone using TestFlight.

This is unfortunately a bit more complicated than the Android setup und will take about an hour to do:

  1. Follow the steps outlined in Thunkable docs → Publish to App Store (iOS) to send a build of your app to your AppStore Connect account. You don’t have to do the ‘Next Steps - App Store Connect’ part yet.
  2. Follow the steps outlined in Thunkable docs → iOS Setup and add your App ID to the Thunkable Push_Notification 1 element.
  3. Follow the steps outlined in Thunkable docs → Adding Push Notifications to re-send your app to your AppStore Connect account.
  4. Test your app on your phone using TestFlight:
    1. Submit your app to TestFlight (see https://academy.thunkable.com/in-app-purchases/overview/ios-app-store-setup#dev7e89e149d for how to)
    2. Add yourself as a tester using a testing group
    3. Install the TestFlight app from the AppStore on your phone
    4. Open the TestFlight app and download your app
💡
We will add detailed walk through videos soon.
💡
Questions? Reach out in the Bubble forum: https://forum.bubble.io/t/native-mobile-app-in-5min-for-60/194022
‣
4. Sending push notifications
💡
OneSignal will automatically allocate a ‘Player ID’ to every app that is installed. This ID is used to identify phones to send the notifications to. When using Henry, the current users Player ID can be found in the ‘Henry: Push Notification’ element and used in workflows. It is good practice to save this to the current user like this:
image

You can send push notifications either directly from your OneSignal account (mainly used to send notifications to all users) or from Bubble (mainly used to send notifications to specific users)

Sending push notifications from OneSignal

Go to OneSignal, find your app, click on ‘New Push’, and follow the dialog

image

Sending push notifications from Bubble:

💡
Henry’s push notification features is currently in beta and only works in combination with other 3rd party OneSignal plugins for Bubble. We are currently working on extending the Henry | Push Notifications plugin so it can be used stand alone without other 3rd party plugins.
  1. Install any OneSignal Bubble Plugin to your app. We recommend this free one here: https://bubble.io/plugin/onesignal-1550111582496x405806558737334300.
  2. Use the ‘OneSignal - Send push notification by Player IDs’ workflow (see the note regarding saving the player ID above).
    3. image

‣
In-App-Purchases (IAP)
💡
On both, Apple and Android devices you won’t be able to test IAP on your installed demo app, but you will need to upload the app to AppStore / PlayStore and install it to your phone via TestFlight / internal testing (we will walk you through this below). To do so, you will need a Thunkable pro subscription.
💡
Unfortunately setting up and testing IAP requires us to set up some stuff in the background, which can seem a bit daunting. But don’t worry, the process is pretty straight forward and we will guide you through all the necessary steps (+videos are coming soon!).

Here is how to set it up:

⚠️ Please make sure you are using the IAP & Push version of the Henry Thunkable template

‣
1. Set up your app listing
💡
If you have already uploaded / published a build of your app in the App Store you can skip this step.

The first thing you need to do is to set up your app listings in App Store Connect (iOS) and the Google Play Developer Console (Android). You can find the respective guides in Thunkable’s documentation (you don’t have to upload a build or publish your app yet):

‣
2. Set up your product ID(s) in AppStore Connect and / or Google Play Console

Next, you need to establish a set of product IDs AppStore Connect and / or Google Play Console

‣
3. Upload a build of your app to App Store Connect (iOS) and the Google Play Developer Console (Android) and download a test version of your app via TestFlight / Internal Testing
‣
iOS
  1. Follow the steps outlined in Thunkable docs → Publish to App Store (iOS) to send a build of your app to your AppStore Connect account. You don’t have to do the ‘Next Steps - App Store Connect’ part yet.
  2. Submit your app to TestFlight (see https://academy.thunkable.com/in-app-purchases/overview/ios-app-store-setup#dev7e89e149d for how to)
  3. Add yourself as a tester using a testing group
  4. Install the TestFlight app from the AppStore on your phone
  5. Open the TestFlight app and download your app
  6. Don’t forget to upload a screen shot under review information (size 640 x 920). For testing purposes you can just use a random app screen shot of that size. Eg this one here.
‣
Android:
  1. Follow the steps outlined in https://docs.thunkable.com/publish-to-play-store-android. You don’t have to submit your app yet. However, even for internal testing, you will need to upload screenshots. You should be able to use any image file with the correct dimensions for now.
  2. Then use ‘Internal Testing’ to download a version of your app to your phone.
‣
5. Trigger IAPs from Bubble using the Henry plugin

Once all of the above is set up, you can use the Henry plugin in Bubble to trigger In-App-Purchases for subscriptions or items:

  1. Put the Henry plugin element ‘Henry:In-App-Purchases’ on the page
  2. Use the element’s workflow actions ‘Purchase Subscription’ or ‘Purchase Item’ to trigger purchases
    3. image
    image
  3. After triggering the workflow in step 2, the user will be prompted to buy an item. You will need to listen to the response for the transaction by adding two events to your workflow section:
    1. ‘Henry:In-App-Purchases A An item or subscription is purchased successfully’. In case of a successful transaction, it’s important to save the transaction receipt to Bubble’s database, so you later know that a users has purchased and item or subscription. We recommend to create a data type ‘purchase’ for this and add the following fields (see picture):
      2. image
    2. ‘Henry:In-App-Purchases A The transaction had an error’. In case the transaction is not concluded successfully, the element will trigger an error event. E.g. if the user cancels the transaction. You don’t necessarily have to do anything with this information, but it can be useful to prompt the user to try again etc.
      3. image
‣
Acknowledge Android Purchases and Subscription

For Android, when a user initiates a transaction, it must be completed by acknowledging the purchase. This acknowledgement communicates to Google Play that you have granted entitlement for the purchase and completes the transaction. If you fail to complete this acknowledgement step your subscriptions will revert in a period of 3 days from the time of purchase.

  1. First, you need to set up a Google Service Account and generate an access key. This will be used below to authenticate your app with the Google Play API. You can follow the instructions outlined in: https://thenicholasrbarrowcompany.gitbook.io/bubble-plugins/google-service-account/google-service-account-plugin/prerequisites. If you need more details on how to set up the Service Account, see here: https://academy.thunkable.com/in-app-purchases/overview/android-play-store-setup#step-4-setup-your-google-cloud-account-and-android-service-account. However, in the last step, please select P12 instead of JSON and then go back to the last step in https://thenicholasrbarrowcompany.gitbook.io/bubble-plugins/google-service-account/google-service-account-plugin/prerequisites to generate your private key.
  2. Install the free Google Service Account plugin to your Bubble app.
  3. Use the below sequence of workflows to Authenticate with the Google Play API and acknowledge the purchase:
    4. image
    ‣
    1. Create Assertion
    • Service Account Email: The email account associated with your service account.
    • Scope: https://www.googleapis.com/auth/androidpublisher
    • Email to Impersonate: Email address the service account should perform actions on behalf of; usually a super-admin in your Google organization.
    • key: They key downloaded from the .PEM file in step 1 above. The same key is reusable.
    image
    ‣
    2. Google API - Request Bearer Token
    • Takes the result of the previous step as inpt
    image
    ‣
    3. Henry: In-app-purchases - Acknowledge Android purchase
    • token: the purchase token you have saved when the user purchased the item
    • Authorization: Write the word ‘Bearer’ plus an empty space and then add the temporary access token generated in the step above.
    • If the acknowledgement is successful, the API will not return any value.
    image

Validating purchase receipts

Sometimes its’ necessary to validate an earlier purchase. E.g. to check if a subscription is still valid or if it has been cancelled and expired. While this is pretty straight forward for iOS, its a bit more complicated for Android. Here is how it’s done:

‣
Apple
  1. Follow the steps outlined in https://academy.thunkable.com/in-app-purchases/overview/ios-app-store-setup#create-an-app-password to create an app-specific password.
  2. In-app-purchases - Validate iOS receipt workflow to validate the receipt.

    3. This workflow step will return an object with information about the purchase that you are validating. You can use this information e.g. to make changes to the user and grant them premium features. You can find more information on how to interpret the return data here https://developer.apple.com/documentation/appstorereceipts/responsebody or here https://academy.thunkable.com/in-app-purchases/overview/verify-ios-purchases#:~:text=Learn more about the data this API call returns

    💡
    Please note: there are two workflows:
    • In-app-purchases (testing) - Validate iOS receipt (Sandbox URL): Used for testing (e.g. in TestFlight)
    • In-app-purchases (testing) - Validate iOS receipt (Production URL): Used in production mode (e.g. for your actual live client subscriptions)
    image
‣
Android
  1. First, you need to set up a Google Service Account and generate an access key. This will be used below to authenticate your app with the Google Play API. You can follow the instructions outlined in: https://thenicholasrbarrowcompany.gitbook.io/bubble-plugins/google-service-account/google-service-account-plugin/prerequisites. If you need more details on how to set up the Service Account, see here: https://academy.thunkable.com/in-app-purchases/overview/android-play-store-setup#step-4-setup-your-google-cloud-account-and-android-service-account. However, in the last step, please select P12 instead of JSON and then go back to the last step in https://thenicholasrbarrowcompany.gitbook.io/bubble-plugins/google-service-account/google-service-account-plugin/prerequisites to generate your private key.
  2. Install the free Google Service Account plugin to your Bubble app.
  3. Use the below sequence of workflows to Authenticate with the Google Play API and acknowledge the purchase:
    4. image
    ‣
    1. Create Assertion
    • Service Account Email: The email account associated with your service account.
    • Scope: https://www.googleapis.com/auth/androidpublisher
    • Email to Impersonate: Email address the service account should perform actions on behalf of; usually a super-admin in your Google organization.
    • key: They key downloaded from the .PEM file in step 1 above. The same key is reusable.
    image
    ‣
    2. Google API - Request Bearer Token
    • Takes the result of the previous step as inpt
    image
    ‣
    3. In-app-purchases - Validate Android receipt

URLs and sharing

‣
Open URL in app

Use the workflow action ‘Henry: Open URL in app’ to open a URL in the app in modal.

image
‣
Open URL in browser

Use the workflow action ‘Henry: Open URL in browser’ to open a URL on the phone’s default browser.

image
‣
Trigger native share

Use the workflow action ‘Henry: Trigger share’ to trigger a native share dialog.

image

Play / display media

‣
Play Audio

Henry comes with a built-in audio player. Use the workflow action ‘Henry: Play audio’ to play an audio file from a URL ending in .mp3, .wav, etc.

image

The URL can also point to the URL of a file stored in the app’s data base. Please make sure you use the thing’s file’s URL, e.g.

image

Besides playing an audio file, you also have the following actions available:

  • Henry: Pause audio
  • Henry: Resume audio
  • Henry: Stop audio
‣
View PDF

Henry comes with a built-in PDF viewer. Use the workflow action ‘Henry: View PDF in app’ to display a PDF from a URL ending in .pdf.

image

The URL can also point to the URL of a file stored in the app’s data base. Please make sure you use the thing’s file’s URL, e.g.

image
‣
Video player

Henry comes with a built-in video player. Use the workflow action ‘Henry: Play video in app’ to play a video from a URL ending in .mp4, .mov, etc..

image

The File URL can also point to the URL of a file stored in the app’s data base. Please make sure you use the thing’s file’s URL, e.g.

image

‣
Image viewer

Henry comes with a built-in image viewer Use the workflow action ‘Henry: View image in app’ to view an image from a URL ending in .jpeg, etc..

image

The File URL can also point to the URL of a file stored in the app’s data base. Please make sure you use the thing’s file’s URL, e.g.

image

Select / record media

‣
Scan barcodes
  1. Place the ‘Henry: Barcode scanner’ element on the page
  2. Use the ‘Scan barcode’ workflow action to open the camera to scan a barcode.
    3. image
  3. If the user scans a barcode, an event ‘Barcode is scanned’ is triggered. You can use this event to create a workflow. E.g. if user confirms event with Event ID ‘scan1’, do something.
    4. image
‣
Record videos
  1. Place the ‘Henry: Video recorder’ element on the page
  2. Use the ‘Record video’ workflow action to open the camera and start recording.
    3. image
  3. Once the user clicks on ‘Stop’, the recording is stopped, the video is sent back to Bubble, and an event Video is recorded’ is triggered. You can use this event to create a workflow. E.g. if user confirms event with Event ID ‘video1’, do something.

    4. ⚠️  Make sure to use this workflow to save the video file in a new thing. ⚠️  IMPORTANT: Make sure to add the ‘:saved to S3’ option. This make sure that the actual video file is saved on AWS. Otherwise Bubble will just save the link to Thunkable’s temporary storage and you will likely lose your file.

    image
    image
‣
Record audio
  1. Place the ‘Henry: Audio recorder’ element on the page
  2. Use the ‘Start audio recording’ workflow action to start an audio recording. The recording will start in the background, without any visual cues.
    3. image
  3. Use the ‘Stop audio recording’ workflow action to stop an audio recording. The recorded audio file is then sent back to Bubble, and an event ‘Audio is recorded’ is triggered. You can use this event to create a workflow. E.g. if user confirms event with Event ID ‘audio1’, do something.
    4. image
    image

    ⚠️  Make sure to use this workflow to save the video file in a new thing. ⚠️  IMPORTANT: Make sure to add the ‘:saved to S3’ option. This make sure that the actual video file is saved on AWS. Otherwise Bubble will just save the link to Thunkable’s temporary storage and you will likely lose your file.

    image
‣
Select image from library or take with camera
  1. Place the ‘Henry: Camera and Library’ element on the page
  2. Use the ‘Get image from camera’ or ‘Get image from photo library’ workflow action to prompt the user to take or select a photo.
    3. image
  3. Once the user has selected or taken a photo, the image is sent back to Bubble, and an event ‘An image is captured / selected’ is triggered. You can use this event to create a workflow. E.g. if user confirms event with Event ID ‘camera1’, do something. Make sure to use this workflow to save the image file in a new thing.
    4. image

    ⚠️  IMPORTANT: Make sure to add the ‘:saved to S3’ option. This make sure that the actual file is saved on AWS. Otherwise Bubble will just save the link to Thunkable’s temporary storage and you will likely lose your file.

    image

🔗 Further information and FAQ

💡
Questions? Reach out in the Bubble forum: https://forum.bubble.io/t/native-mobile-app-in-5min-for-60/194022

‣
subpages
Bubble demo

XYouTube

Home

Mobile

Chrome Extensions

Newsletter

About

Š 2023 bubbleHacks by NC Labs GmbH, Switzerland. All rights reserved.