feat(docs): update some tutorials

marchbold · marchbold · commit af8382357ad3 · 2025-10-11T13:37:44.000+10:00
diff --git a/docs/tutorials/android-device-debugging.md b/docs/tutorials/android-device-debugging.md
@@ -15,6 +15,11 @@ To enable "Developer mode":
 - Tap **Build number** several times and you should see a dialog that says "you're X taps away from being a developer".
 - Continue tapping the build number until the developer mode is enabled. 
 
+:::note
+The specific loction of the **Build number** can vary based on the manufacturer and android version. You may have to explore your settings a bit to find it.
+:::
+
+
 To enable USB debuging:
 
 - Go to the settings menu
@@ -24,8 +29,9 @@ To enable USB debuging:
 
 You will now be able to connect a usb cable to your device and use the `adb` tool to install applications (APKs) and access the device logs. 
 
-
-
+:::note
+When you first connect a new computer using USB, depending on the Android version you may have an authorisation dialog appear to authorise the connection to the computer. 
+:::
 
 
 
diff --git a/docs/tutorials/device-logs.md b/docs/tutorials/device-logs.md
@@ -10,7 +10,8 @@ Getting access to the device logs often yields additional information when attem
 
 On Android it is relatively simple to get the device logs. The debugger command line utility (`adb`/`adb.exe`) can be used to output the logs along with installing your application and is packaged as part of AIR at `AIRSDK/lib/android/bin`. If you have installed the Android SDK you can also use the version from there.
 
-> Note: It is important you have set your device into debug mode.
+> Note: It is important you have set your device into debug mode. See [Android Device Debugging](android-device-debugging.md).
+
 
 ### macOS (OSX)
 
@@ -19,12 +20,18 @@ To access the logs:
 - open a Terminal
 - run `adb logcat`
 
-You can get more relevant information by using grep to filter the logs. For example, we often use the following:
+
+#### Filtering
+
+You can control the output by using `grep` to filter the logs. For example, we often use the following:
 
 ```
 adb logcat | grep -E --color=always 'distriqt|AndroidRuntime|System.err'
 ```
 
+> Note: If we ask you to supply logs for debugging please provide an unfiltered log. Filtering can accidentally remove entries of interest.
+
+
 
 ### Windows
 
diff --git a/docs/tutorials/getting-started-animate.md b/docs/tutorials/getting-started-animate.md
@@ -1,5 +1,5 @@
 ---
-title: Getting Started - Animate
+title: Animate
 sidebar_label: Animate
 ---
 
diff --git a/docs/tutorials/getting-started-flashbuilder4.5.md b/docs/tutorials/getting-started-flashbuilder4.5.md
@@ -1,8 +1,21 @@
 ---
-title: Getting Started - Flash Builder 4.5
+title: Flash Builder 4.5
 sidebar_label: Flash Builder 4.5
 ---
 
+:::warning
+Flash Builder is no longer supported by our extensions. Flash Builder links directly into the legacy build methods of the AIR SDK and as such cannot support the latest Android features and won't work with our extensions any longer. 
+
+You may be able to use it as an editor but the packaging process won't work. You'll need to use the AIR SDK directly to package your application. We encourage you to move to a more modern development environment.
+:::
+
+:::caution
+Last release: Adobe Flash Builder 4.5, released in May, 2011.
+
+Adobe Flash Builder reached end of core support in 2017 and end of extended support in 2019.
+:::
+
+
 An AIR Native Extension (ANE) is a single file with the extension `ane`. This file contains all of the native and actionscript libraries that are implemented by this extension. You don’t need access to a separate SWC file or to the source code to be able to use the ANE.
 
 Here we will add the extension to your build process so that your application can use the functionality provided by the extension.
diff --git a/docs/tutorials/getting-started-flashbuilder4.7.md b/docs/tutorials/getting-started-flashbuilder4.7.md
@@ -1,8 +1,20 @@
 ---
-title: Getting Started - Flash Builder 4.6/4.7
+title: Flash Builder 4.6/4.7
 sidebar_label: Flash Builder 4.6/4.7
 ---
 
+:::warning
+Flash Builder is no longer supported by our extensions. Flash Builder links directly into the legacy build methods of the AIR SDK and as such cannot support the latest Android features and won't work with our extensions any longer. 
+
+You may be able to use it as an editor but the packaging process won't work. You'll need to use the AIR SDK directly to package your application. We encourage you to move to a more modern development environment.
+:::
+
+:::caution
+Last release: Adobe Flash Builder 4.7, released in Dec, 2012.
+
+Adobe Flash Builder reached end of core support in 2017 and end of extended support in 2019.
+:::
+
 ## Add the Extension
 
 An AIR Native Extension (ANE) is a single file with the extension `ane`. This file contains all of the native and actionscript libraries that are implemented by this extension. You don’t need access to a separate SWC file or to the source code to be able to use the ANE.
diff --git a/docs/tutorials/getting-started-flashdevelop.md b/docs/tutorials/getting-started-flashdevelop.md
@@ -1,5 +1,5 @@
 ---
-title: Getting Started - Flash Develop
+title: Flash Develop
 sidebar_label: Flash Develop
 ---
 
diff --git a/docs/tutorials/getting-started-intellij.md b/docs/tutorials/getting-started-intellij.md
@@ -1,5 +1,5 @@
 ---
-title: Getting Started - IntelliJ
+title: IntelliJ
 sidebar_label: IntelliJ
 ---
 
diff --git a/docs/tutorials/ios-icons-assets-car.md b/docs/tutorials/ios-icons-assets-car.md
@@ -24,30 +24,46 @@ Contents:
 - [Supporting previous versions of iOS](#supporting-previous-versions-of-ios)
 
 
+## Creating the Asset Catalogue
 
-## Method 1 Command Line
 
-:::note
-You will need a macOS machine with Xcode 9+ for this method to generate the `Assets.car` file
+### Method 1: AIR-ImageScripts
+
+:::tip Recommended Approach
+You will need a macOS machine with Xcode and imagemagik for this method, however the files can be transferred afterwards. 
 :::
 
-This is the method we prefer as it is simpler to update and create than having to drag files into Xcode. We have a  script that downloads the required assets, resizes an icon and launch screen image appropriately and calls the xcode utilities to generate the Assets.car (and launch screen).
+This is the method we prefer as it is simpler to update and create than having to drag files into Xcode. We have a script that downloads the required assets, resizes an icon and launch screen image appropriately and calls the xcode utilities to generate the Assets.car (and launch screen).
 
 The script is available in the [AIR-ImageScripts repository](https://github.com/distriqt/AIR-ImageScripts) 
 
 You will need to have installed `imagemagick` and the **xcode command line utilities** (see details in the repository if you need help installing them).
 
-To use it, create an `icon.png` file that is a high resolution icon file (we suggest 1024x1024) and a `launch.png` launch screen image (we suggest a large 2732x2732 pixel image). Place them in a directory and open a terminal at this location. You can either clone the repository and use the `generate.sh` script directly or call it as below:
+To use it you will need to create 4 files for your icon. We require a foreground and background for your main icon so we can correctly create the adaptive icons for various situations. Then also a monochrome version of your foreground icon for themed environments and then a complete alternative icon to be used in dark situations on iOS. 
+
+These four base images are used to construct the icons for each of the platforms:
+
+- `icon-foreground.png`: should be a transparent icon with no background which will be layered over the background and centered on the launch image
+- `icon-background.png`: should be a filled image which constitutes the background of adaptive icons and the launch image (generally a solid colour)
+- `icon-monochrome.png`: similar to the foreground icon except this should be monochrome and will be tinted by the OS to colour match the user's theme
+- `icon-dark.png`: a specific dark image to be used as the dark icon on iOS
+
+All of these files should be high resolution (we suggest 1024x1024) 
+
+Next create a `launch.png` launch screen image (we suggest a large 2732x2732 pixel image). 
+
+Place all these files in a directory and open a terminal at this location. You can either clone the repository and use the `generateIcons` script directly or call it as below:
 
 ```
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/distriqt/AIR-ImageScripts/master/generate.sh)"
+/bin/bash -c "$(curl -fsSL https://github.com/distriqt/AIR-ImageScripts/releases/download/v2.0/generateIcons)"
 ```
 
 Once complete this will have generated an `out` directory that contains 
 
 - `Assets.car` your asset catalogue 
 - `LaunchScreen.storyboardc` directory is your custom launch screen storyboard
-- `icons` directory containing icon images sized for AIR.
+- `icons` directory containing icon images sized for AIR
+- `res` folder containing adaptive icons for Android
 
 Copy these into your application as you require.
 
@@ -80,11 +96,11 @@ You can use the `icons` directory in your application descriptor by adding the f
 </icon>
 ```
 
-## Method 2 Using Xcode
+### Method 2: Using Xcode
 
->
-> Note: You will need a macOS machine with Xcode 9+ for this method to generate the `Assets.car` file
->
+:::note
+You will need a macOS machine with Xcode for this method to generate the `Assets.car` file
+:::
 
 Firstly you will need to open Xcode and create a new application
 
@@ -124,7 +140,11 @@ Firstly you will need to open Xcode and create a new application
 
 
 
-## Method 3 Online tool
+### Method 3: Online tool
+
+:::caution
+We do not recommend this approach as it can cause issues depending on your AIR developer license. This approach can miss resources required by the AIR SDK and cause your application to crash. 
+:::
 
 This is the simplest way if you are a Windows developer. 
 
@@ -147,16 +167,18 @@ You do this by ensuring that it is in the root of your applications source and s
 
 ## Simple Launch Screen
 
-To simplify migration to launch storyboards we have created a simple storyboard that pulls an image from your `Assets.car` and aspect fills it to the screen. You will add a single image to your `Assets.car` alongside your application icons. (If you followed the instructions above this will be the `LaunchImage.png` you added.)
+To simplify migration to launch storyboards we have created a simple storyboard that pulls an image from your `Assets.car` and aspect fills it to the screen. You will add a single image to your `Assets.car` alongside your application icons. 
+
+The AIR Image Scripts process above should have generated this launch screen for you.
+
 
 Download this zip file and extract the `LaunchScreen.storyboardc`. Add it to your application and ensure it is packaged at the root level of your application alongside your `Assets.car`. 
 
 - [LaunchScreen.storyboardc.zip](resources/ios/LaunchScreen.storyboardc.zip)
 
->
-> `LaunchScreen.storyboardc` is a directory but will appear as a "file" (package) on macOS
->
-
+:::note
+`LaunchScreen.storyboardc` is a directory but will appear as a "file" (package) on macOS
+:::
 
 Add the following to the `InfoAdditions` node in your application descriptor:
 
@@ -170,17 +192,22 @@ That is all, you have now implemented a launch storyboard.
 
 
 
-## Supporting previous versions of iOS
+## Launch images
 
-You must also make sure that you include the icons in your application using the icon tags in the application descriptor xml. 
-This ensures that older versions of iOS still have the correct icons packaged and that other platforms still have the appropriate app icons.
+:::note
+This is no longer relevant as the minimum iOS version supported by new apps should support the launch screen approach and the default images are no longer required.
+:::
 
+Recently Apple changed the supported names of the files for the default / launch images. Make sure you have correctly added the default images according to the Adobe docs:
 
+[http://blogs.adobe.com/airodynamics/2015/03/09/launch-images-on-ios-with-adobe-air/](http://blogs.adobe.com/airodynamics/2015/03/09/launch-images-on-ios-with-adobe-air/)
 
-## Launch images
 
-Recently Apple changed the supported names of the files for the default / launch images. Make sure you have correctly added the default images according to the Adobe docs:
+### Supporting previous versions of iOS
+
+
+You must also make sure that you include the icons in your application using the icon tags in the application descriptor xml. 
+This ensures that older versions of iOS still have the correct icons packaged and that other platforms still have the appropriate app icons.
 
-[http://blogs.adobe.com/airodynamics/2015/03/09/launch-images-on-ios-with-adobe-air/](http://blogs.adobe.com/airodynamics/2015/03/09/launch-images-on-ios-with-adobe-air/)
 
 
diff --git a/docs/tutorials/ios-launchscreens.md b/docs/tutorials/ios-launchscreens.md
@@ -20,20 +20,23 @@ Contents:
 - [Adding to AIR](#adding-to-air)
 
 
-# Method 1
+## Method 1
 
-This simple method uses a prebuilt storyboard which pulls an image from your `Assets.car` and fill the screen keeping the aspect ratio (your image may be cropped on some devices depending on the resolution). 
+:::tip Recommended Approach
+:::
 
-We have included these instructions as part of the [Icons, Launch Storyboards and the Assets Catalog](ios-icons-assets-car.md#method-1-command-line) guide.
+This simple method uses a script we have written that builds upon a prebuilt storyboard to show an image from your `Assets.car` and fill the screen keeping the aspect ratio (your image may be cropped on some devices depending on the resolution and the image). 
 
+We have included these instructions as part of the [Icons, Launch Storyboards and the Assets Catalog](ios-icons-assets-car.md#method-1-air-imagescripts) guide.
 
-# Method 2 
 
-Using Xcode
+## Method 2 
 
->
-> Note: You will need a macOS machine with Xcode 9+ for this method to generate the `Assets.car` file
->
+This method uses Xcode directly.
+
+:::note
+You will need a macOS machine with Xcode for this method to generate the `Assets.car` file
+:::
 
 As this process is tightly integrated with generating the `Assets.car` (asset catalog) containing your application icons, we will go through adding the icons first.
 
@@ -70,7 +73,7 @@ Now you have added the application icons we move onto adding the launch storyboa
 
 
 
-## Centered Icon 
+### Centered Icon 
 
 Firstly we need to add the image resource to your asset catalog. 
 
@@ -116,7 +119,7 @@ Firstly we need to add the image resource to your asset catalog.
 
 
 
-## Full Screen Image
+### Full Screen Image
 
 Reference:
 
@@ -127,7 +130,7 @@ https://medium.com/flawless-app-stories/change-splash-screen-in-ios-app-for-dumm
 
 
 
-## Build
+### Build
 
 - Build the project ( Product -> Build).
 - Right-click on your ‘.app’ -> Show in finder.
@@ -141,7 +144,8 @@ https://medium.com/flawless-app-stories/change-splash-screen-in-ios-app-for-dumm
 >
 
 
-# Adding to AIR
+
+## Adding to AIR
 
 Once you have completed your storyboard and added the application icons you can add these to your AIR applicaiton.
 
