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:

ABMaterial - can not get "add to home screen" to work with my icon

On your Android or iPhone, if you launch Chrome or Safari then search for "www.b4x.com" then find "Add to Home Screen" and follow the breadcrumbs you end up with the websites bookmark as a nice little icon on the home screen with the B4X logo in it. Tap it and you are immediately at the website...
www.b4x.com www.b4x.com

INSTALLATION
RUN AS LOCAL HOST
CORRECTIONS AND UPDATES LOG
POSSIBLE ENHANCEMENTS
BROWSER TESTING TO DATE
ADDITIONAL NOTES
 
Last edited:
Click to expand...
JackKirk

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-02.117237/

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

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/[email protected]/")
        '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: 14
Last edited:
JackKirk

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

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

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

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

JackKirk

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

ABM.MaskIcon = "safari-pinned-tab.svg"
Click to expand...
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: 13
Last edited:
You must log in or register to reply here.

Similar Threads

JackKirk
  • Question
B4J Question ABMaterial - can not get "add to home screen" to work with my icon
Replies
6
Views
322
JackKirk
JackKirk
hatzisn
  • Question
B4J Question Jetty Server - HEAD request & error piping
Replies
3
Views
675
hatzisn
hatzisn
MichalK73
  • Question
B4J Question [ABMaterial] Mobile browser problem
Replies
8
Views
1K
alwaysbusy
alwaysbusy
Top