B4J Tutorial ABMaterial - "Add to Home Screen" functionality - principally for Android Chrome and iOS Safari

PREAMBLE

This probably doss not rank as a tutorial but then it is not a question either - so tutorial it is.

The following is the result of my attempt to get my head around the Android Chrome and iOS Safari browsers "Add to Home Screen" capability - i.e. the ability to save a website's bookmark as an icon on the host smartphone's home screen.

In the exercise I test what icons actually get used - with results somewhat different to what I was led to believe would happen - see BROWSER TESTING TO DATE.

The exercise basically adds the "Add to Home Screen" capability to Alain's introductory ABM template:

https://www.b4x.com/android/forum/t...-absolute-beginners-update-2024-05-02.117237/

And uses Alain's suggestion as a starting point:


INSTALLATION
RUN AS LOCAL HOST
CORRECTIONS AND UPDATES LOG
POSSIBLE ENHANCEMENTS
BROWSER TESTING TO DATE

ADDITIONAL NOTES
 
Last edited:

JackKirk

Well-Known Member
Licensed User
Longtime User
INSTALLATION

Step 1

Install ABMMini on your D: drive - see:

https://www.b4x.com/android/forum/t...-absolute-beginners-update-2024-05-17.117237/

Make sure you download ABMMini240517.zip (note the 240517).

It is assumed that you end up with a folder [D:\ABMMini] containing:

Library folder
Template folder
LICENSE.TXT
README.txt

and these additions to your B4J [Additional Libraries] folder:

ABMaterial.jar
...
thumbnailator-0.4.8.jar

Step 2

Go to your B4J [Additional Libraries] folder and right click on [ABMServer.b4xlib] then use 7-Zip or similar to open archive. Copy all modules to folder [D:\ABMMini\Template].

Your [D:\ABMMini\Template] folder should now contain:

ABMApplication.bas
ABMCacheControl.bas
ABMCacheScavenger.bas
ABMCacheV3.bas
ABMErrorHandler.bas
ABMPageTemplate.bas
ABMRootFilter.bas
ABMServer.bas
ABMUploadHandler.bas
DBM.bas
Template.b4j
Template.b4j.meta

Step 3

Download the zip file [Add_to_Home_Screen_4_ABM.zip].

Unzip it and copy the folder [Files] into [D:\ABMMini\Template].

Your [D:\ABMMini\Template\Files] folder should now contain:

16x16.png
32x32.png
96x96.png
128x128.png
150x150.png
180x180.png
194x194.png
570x570.png
site.webmanifest

Step 4

Launch B4J project [D:\ABMMini\Template\Template.b4j]

[Files Manager] > [Add Files] > navigate to [D:\ABMMini\Template\Files] > select all files > [Open]

[Libraries Manager] > uncheck [ABMServer]

[Project] > [Add Existing Modules] > navigate to [D:\ABMMini\Template] > select all modules > [Open] > [Copy to project folder] > [OK]

Step 5

With B4J project [D:\ABMMini\Template\Template.b4j] still launched...

Edit AppStart procedure in Main module so that it reads (changes between <<<<START & <<<<END):

B4X:
Sub AppStart (Args() As String)
    ' must be the first line in AppStart. DO NOT DELETE OR CHANGE!
    ' ------------------------------------------------------------
    ABM.SessionCacheControlV3 = "ABMCacheV3"
    ' ------------------------------------------------------------
 
    Dim DonatorKey As String = ""
    Server.Initialize("", DonatorKey, "template") ' Application = ' the handler that will be used in the url e.g. http://localhost:51042/template
    ' some parameters
    Server.Port = 51042
    ' the user needs to login, set to true. the CheckLogin() method will be called if one tries to login
    Server.NeedsAuthorization = False
    Server.StartPage = "ABMPageTemplate" ' the first page of your app
    Server.CacheScavengePeriodSeconds = 15 * 30 ' 15 minutes
    Server.SessionMaxInactiveIntervalSeconds = 30 * 60 ' 30 minutes
    Server.UploadFolder = "uploads"
    Server.UploadMaxSize = 1024 * 1024
 
    ' Build the Theme
    BuildTheme("mytheme")
 
    ' create the pages
    Dim myPage As ABMPageTemplate
    myPage.Initialize  
    ' add the pages to the app
    Server.AddPage(myPage.page)
    ' do the same for your own pages: dim, initialize and Server.AddPage
    ' ...
 
    ' start the server
    If Server.PortSSL <> 0 Then
        Server.StartServerHTTP2("keystore.jks", "KeyStorePassword", "KeyManagerPassword")
    Else
        Server.StartServer
    End If
 
'<<<<
'<<<< START - adds "Add to Home Screen" icon capability to ABMMini
'<<<<       - see also code block in ABMApplication module
'<<<<
'<<<< See:
'<<<< https://www.b4x.com/android/forum/threads/abmaterial-can-not-get-add-to-home-screen-to-work-with-my-icon.160494/post-985600
'<<<<

    'At this point, on very first run, File.DirApp & "\www\template\images" folder
    'has just been created so now safe to copy various icons into it
    File.Copy(File.DirAssets, "180x180.png", File.DirApp & "\www\template\images", "apple-touch-icon.png")
    File.Copy(File.DirAssets, "150x150.png", File.DirApp & "\www\template\images", "mstile-150x150.png")
    File.Copy(File.DirAssets, "16x16.png", File.DirApp & "\www\template\images", "favicon-16x16.png")
    File.Copy(File.DirAssets, "32x32.png", File.DirApp & "\www\template\images", "favicon-32x32.png")
    File.Copy(File.DirAssets, "96x96.png", File.DirApp & "\www\template\images", "favicon-96x96.png")
    File.Copy(File.DirAssets, "128x128.png", File.DirApp & "\www\template\images", "favicon-128x128.png")
    File.Copy(File.DirAssets, "194x194.png", File.DirApp & "\www\template\images", "favicon-194x194.png")
    File.Copy(File.DirAssets, "site.webmanifest", File.DirApp & "\www\template\images", "site.webmanifest")

    'Actual observed use of various icons:
 
    'favicon-194x194.png - icon for Android Chrome "Add to Home Screen" (Pixel 3 Android 12)
    '                                                                   (Pixel 8  AWS Device Farm Android 14)
    'favicon-180x180.png - icon for iOS Safari "Add to Home Screen" (iPhone 7 iOS 15.8.1)
    '                                                               (iPhone 15 Pro Max AWS Device Farm iOS 17.3.1)
    'favicon-32x32.png - icon for Windows 10 Chrome
    'favicon-32x32.png - icon for Windows 10 Firefox
 
    'Are more icons needed? - other browsers?, newer/older browsers?
 
'<<<<
'<<<< END - adds "Add to Home Screen" icon capability to ABMMini
'<<<<
 
    ' redirect the output of the logs to a file if in release mode
    Server.RedirectOutput(File.DirApp, "logs.txt")
 
    Log("Open with:")
    LogError("localhost:" & Server.Port & "/template")
   
    StartMessageLoop
End Sub

Edit Initialize procedure in ABMApplication module so that it reads (changes between <<<<START & <<<<END):

B4X:
Public Sub Initialize()
    Pages.Initialize
    PageNeedsUpload.Initialize
    ABM.AppVersion = Main.server.AppVersion
    ABM.AppPublishedStartURL = Main.server.AppPublishedStartURL
    Dim DonatorKey As String = Main.Server.DonatorKey
    InitialPage = Main.Server.StartPage
          
    ' add your icons
    ' ABM.AddAppleTouchIcon("", "")
    ' ABM.AddMSTileIcon("", "")
    ' ABM.AddFavorityIcon("", "")
 
'<<<<
'<<<< START - adds "Add to Home Screen" icon capability to ABMMini
'<<<<       - see also code block in Main module
'<<<<
'<<<< See:
'<<<< https://www.b4x.com/android/forum/threads/abmaterial-can-not-get-add-to-home-screen-to-work-with-my-icon.160494/post-985600
'<<<<
 
    ABM.AddAppleTouchIcon("apple-touch-icon.png", "180x180")
    ABM.AddMSTileIcon("mstile-150x150.png", "150x150")
    ABM.AddFavorityIcon("favicon-16x16.png", "16x16")
    ABM.AddFavorityIcon("favicon-32x32.png", "32x32")
    ABM.AddFavorityIcon("favicon-96x96.png", "96x96")
    ABM.AddFavorityIcon("favicon-128x128.png", "128x128")
    ABM.AddFavorityIcon("favicon-194x194.png", "194x194")
 
    'ABM.AppVersion = ABMShared.AppVersion
    'ABM.AppPublishedStartURL = ABMShared.AppPublishedStartURL
    ABM.MaskIcon = "safari-pinned-tab.svg"
    ABM.MaskIconColor = ABM.COLOR_AMBER
    ABM.MaskIconColorIntensity = ABM.INTENSITY_DARKEN3
    ABM.MSTileColor = ABM.COLOR_AMBER
    ABM.MSTileColorIntensity = ABM.INTENSITY_DARKEN3
 
    'Sets background color of Android Chrome and iOS Safari address bar
    ABM.AndroidChromeThemeColor = ABM.COLOR_LIGHTBLUE
    ABM.AndroidChromeThemeColorIntensity = ABM.INTENSITY_DARKEN1
 
    'Commenting this statement out seemed to have no bad effect on
    '"Add to Home Screen" with Android Chrome and iOS Safari - but do
    'other browsers require it?
    'Its contents seem to need to define location of resources referred
    'to in various ABM.ADD... statements above, suggested contents:
    '{
    '    "name": "",
    '    "icons": [
    '        {
    '            "src": ".../images/apple-touch-icon.png",
    '            "sizes": "180x180",
    '            "type": "image/png"
    '        },
    '        {
    '            "src": ".../images/mstile-150x150.png",
    '            "sizes": "150x150",
    '            "type": "image/png"
    '        },
    '        {
    '            "src": ".../images/favicon-16x16.png",
    '            "sizes": "16x16",
    '            "type": "image/png"
    '        },
    '        {
    '            "src": ".../images/favicon-32x32.png",
    '            "sizes": "32x32",
    '            "type": "image/png"
    '        },
    '        {
    '            "src": ".../images/favicon-96x96.png",
    '            "sizes": "96x96",
    '            "type": "image/png"
    '        },
    '        {
    '            "src": ".../images/favicon-128x128.png",
    '            "sizes": "128x128",
    '            "type": "image/png"
    '        },
    '        {
    '            "src": ".../images/favicon-194x194.png",
    '            "sizes": "194x194",
    '            "type": "image/png"
    '        }
    '    ],
    '    "theme_color": "#ffffff",
    '    "background_color": "#ffffff",
    '    "display": "standalone"
    '}
    ABM.Manifest = "site.webmanifest"
 
'<<<<
'<<<< END - adds "Add to Home Screen" icon capability to ABMMini
'<<<<

    #If RELEASE
        'ABM.ActivateUseCDN(DonatorKey, "https://cdn.jsdelivr.net/gh/RealAlwaysbusy/ABMaterial@v3.81-rc1/")
        'ABM.PreloadAllJavascriptAndCSSFiles=True    ' NEW
        ABM.ActivateGZip(DonatorKey, 1000) ' NEW
 
        Dim folders As List ' NEW
        folders.Initialize
        folders.Add(File.DirApp & "/www/" & Main.server.AppName & "/images")
        ABM.ActivatePNGOptimize(DonatorKey, folders, False , 9, False, True )
    #End If
 
    ' build the local structure IMPORTANT!
    BuildPage
 
End Sub

[File] > [Save] to update project.

Summarising

When the Template app is launched:
  • in Main.AppStart - copies raw icon files ([194x194.png] etc) from File.DirAssets (i.e. [D:\ABMMini\Template\Files]) into File.DirApp & www\template\images (i.e. [D:\ABMMini\Template\Objects\www\template\images]) - at the same time renaming as [favicon-194x194.png] etc.
  • similarly copies [site.webmanifest]
  • in ABMApplication.Initialize - creates webpage references to icon files via ABM.Add... statements
 

Attachments

  • Add_to_Home_Screen_4_ABM.zip
    20.5 KB · Views: 112
Last edited:

JackKirk

Well-Known Member
Licensed User
Longtime User
RUN AS LOCAL HOST

Just run in Debug mode then, on a device on the same local network, launch a browser and enter the URL [localhost:51042/template]

If this does not work you may need to find the local IP address of the PC (something like 192.168.1.109) then use a URL like [192.168.1.109:51042/template]

If your device is a smartphone, click ... (top RH corner, Android Chrome) or [^] (box with up arrow, middle bottom, iOS Safari)

[Add to Home Screen] > should create a pop-up panel showing the icon it plans to use and allow you to add text > [Add]

If you go to home screen there should be a shortcut icon that, when clicked, takes you directly to the website.
 
Last edited:

JackKirk

Well-Known Member
Licensed User
Longtime User
CORRECTIONS AND UPDATES LOG

In post #2 added:

Make sure you download ABMMini240502.zip (note the 240502).
 
Last edited:

JackKirk

Well-Known Member
Licensed User
Longtime User
POSSIBLE ENHANCEMENTS

I get the unsettling feeling that there is a lot going on under the covers and this may vary by browser and or browser vintage - for example I found that you seemed to be able to comment out the statement

ABM.Manifest = "site.webmanifest"

in ABMApplication.Initialize on the browsers I tested - but is this true for all browsers?

It is also possible that there is some edge case browser that does not work with the indicated set up - in which case you may need to add raw icons to File.DirAssets (i.e. [D:\ABMMini\Template\Files]), copy them, reference them with ABM.Add... statements and augment the manifest.
 
Last edited:

JackKirk

Well-Known Member
Licensed User
Longtime User
BROWSER TESTING TO DATE

For testing purposes each supplied icon has a unique single number clearly shown in it (16, 32, 96, 128, 150, 180, 194).

Actual observed use of various icons:
  • favicon-194x194.png - icon for Android Chrome "Add to Home Screen" (Pixel 3 Android 12) and (Pixel 8 AWS Device Farm Android 14)
  • apple-touch-icon.png - (180x180) icon for iOS Safari "Add to Home Screen" (iPhone 7 iOS 15.8.1) and (iPhone 15 Pro Max AWS Device Farm iOS 17.3.1)
  • favicon-32x32.png - icon for Windows 10 Chrome
  • favicon-32x32.png - icon for Windows 10 Firefox
If you test it on a browser not in the above lists please tell me and I will update this list - please include device, browser and version, OS and version.

Note that I have not seen mstile-150x150.png pop up anywhere in my testing - just what is it required for?

Also, I don't have the foggiest notion what this statement is about:

ABM.MaskIcon = "safari-pinned-tab.svg" <<< See next post
 
Last edited:

JackKirk

Well-Known Member
Licensed User
Longtime User
Also, I don't have the foggiest notion what this statement is about:

ABM.MaskIcon = "safari-pinned-tab.svg"
I should have googled instead of firing questions into the ether.

I found:
https://www.macrumors.com/how-to/pin-tabs-safari-iphone-ipad-ios/

Which pretty well sums it up.

It is an iOS/iPadOS (16+?) feature - so no implications to any other browser.

To implement:

Step 1:

Create an .svg file - google it - you need to use a SVG editor of which there seem to be a wide variety of online and off line options.

I used:

https://mediamodifier.com/free-svg-editor

which proved pretty painless and created a real simple SVG file (see attached - zipped to get around attached file type restrictions).

After unzipping you can open this file with Windows Notepad or similar.

Step 2:

Rename .svg file as safari-pinned-tab.svg and add to [D:\ABMMini\Template\Files] folder you created at INSTALLATION Step3 which should now contain:

16x16.png
32x32.png
96x96.png
128x128.png
150x150.png
180x180.png
194x194.png
570x570.png
site.webmanifest
safari-pinned-tab.svg

Step 3:

With B4J project [D:\ABMMini\Template\Template.b4j]:

Edit AppStart procedure in Main module so that it reads (changes between <<<<START & <<<<END):

B4X:
Sub AppStart (Args() As String)
    ' must be the first line in AppStart. DO NOT DELETE OR CHANGE!
    ' ------------------------------------------------------------
    ABM.SessionCacheControlV3 = "ABMCacheV3"
    ' ------------------------------------------------------------
 
    Dim DonatorKey As String = ""
    Server.Initialize("", DonatorKey, "template") ' Application = ' the handler that will be used in the url e.g. http://localhost:51042/template
    ' some parameters
    Server.Port = 51042
    ' the user needs to login, set to true. the CheckLogin() method will be called if one tries to login
    Server.NeedsAuthorization = False
    Server.StartPage = "ABMPageTemplate" ' the first page of your app
    Server.CacheScavengePeriodSeconds = 15 * 30 ' 15 minutes
    Server.SessionMaxInactiveIntervalSeconds = 30 * 60 ' 30 minutes
    Server.UploadFolder = "uploads"
    Server.UploadMaxSize = 1024 * 1024
 
    ' Build the Theme
    BuildTheme("mytheme")
 
    ' create the pages
    Dim myPage As ABMPageTemplate
    myPage.Initialize   
    ' add the pages to the app
    Server.AddPage(myPage.page)
    ' do the same for your own pages: dim, initialize and Server.AddPage
    ' ...
 
    ' start the server
    If Server.PortSSL <> 0 Then
        Server.StartServerHTTP2("keystore.jks", "KeyStorePassword", "KeyManagerPassword")
    Else
        Server.StartServer
    End If
 
'<<<<
'<<<< START - adds "Add to Home Screen" icon capability to ABMMini
'<<<<       - see also code block in ABMApplication module
'<<<<
'<<<< See:
'<<<< https://www.b4x.com/android/forum/threads/abmaterial-can-not-get-add-to-home-screen-to-work-with-my-icon.160494/post-985600
'<<<<

    'At this point, on very first run, File.DirApp & "\www\template\images" folder
    'has just been created so now safe to copy various icons into it
    File.Copy(File.DirAssets, "180x180.png", File.DirApp & "\www\template\images", "apple-touch-icon.png")
    File.Copy(File.DirAssets, "150x150.png", File.DirApp & "\www\template\images", "mstile-150x150.png")
    File.Copy(File.DirAssets, "16x16.png", File.DirApp & "\www\template\images", "favicon-16x16.png")
    File.Copy(File.DirAssets, "32x32.png", File.DirApp & "\www\template\images", "favicon-32x32.png")
    File.Copy(File.DirAssets, "96x96.png", File.DirApp & "\www\template\images", "favicon-96x96.png")
    File.Copy(File.DirAssets, "128x128.png", File.DirApp & "\www\template\images", "favicon-128x128.png")
    File.Copy(File.DirAssets, "194x194.png", File.DirApp & "\www\template\images", "favicon-194x194.png")
    File.Copy(File.DirAssets, "site.webmanifest", File.DirApp & "\www\template\images", "site.webmanifest")  
    File.Copy(File.DirAssets, "safari-pinned-tab.svg", File.DirApp & "\www\template\images", "safari-pinned-tab.svg")

    'Actual observed use of various icons:
 
    'favicon-194x194.png - icon for Android Chrome "Add to Home Screen" (Pixel 3 Android 12)
    '                                                                   (Pixel 8  AWS Device Farm Android 14)
    'favicon-180x180.png - icon for iOS Safari "Add to Home Screen" (iPhone 7 iOS 15.8.1)
    '                                                               (iPhone 15 Pro Max AWS Device Farm iOS 17.3.1)
    'favicon-32x32.png - icon for Windows 10 Chrome
    'favicon-32x32.png - icon for Windows 10 Firefox
 
    'Are more icons needed? - other browsers?, newer/older browsers?
 
'<<<<
'<<<< END - adds "Add to Home Screen" icon capability to ABMMini
'<<<<
 
    ' redirect the output of the logs to a file if in release mode
    Server.RedirectOutput(File.DirApp, "logs.txt")
 
    Log("Open with:")
    LogError("localhost:" & Server.Port & "/template")
    
    StartMessageLoop
End Sub

i.e. just added line:

File.Copy(File.DirAssets, "safari-pinned-tab.svg", File.DirApp & "\www\template\images", "safari-pinned-tab.svg")

Step 4:

Run as local host as before.

On an iOS 16+ device you should be able to follow:

https://www.macrumors.com/how-to/pin-tabs-safari-iphone-ipad-ios/

and pin the website with this icon.

I do not have an iPhone with iOS 16+ and have not been able to get this "pinning" to work on an AWS Device Farm iPhone 15 running iOS 17.3.1

So if anyone does have such a device and would care to test this it would be much appreciated.
 

Attachments

  • Mediamodifier-Design.zip
    837 bytes · Views: 119
Last edited:
Top