Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update quick start guides #271

Merged
merged 8 commits into from
Jul 11, 2024
Merged

docs: update quick start guides #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
df15268
docs(ios): update quick start guide to use Portals CLI + add SPM inst…
eric-horodyski Apr 5, 2024
83fe5c8
docs(android): update quick start guide to use Portals CLI
eric-horodyski Apr 5, 2024
fd241ff
fix(docs): update the Windows directory in the Android quick-start gu…
eric-horodyski Apr 9, 2024
ed1d02f
fix(docs): update quick-start images
eric-horodyski Apr 10, 2024
9507be9
fix(docs): update android `.portals.yaml` and `build.gradle` steps.
eric-horodyski Apr 23, 2024
a90d3b5
Added Kotlin Syntax tab for the gradle configuration
carlpoole Jul 3, 2024
d3fc025
default to groovy dsl
carlpoole Jul 3, 2024
86594cb
sync, not help. Oops
carlpoole Jul 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 47 additions & 111 deletions website/docs/for-android/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ This is a walkthrough on how to get a single Portal + web application setup. To

First have your web application ready. We will add some configuration to it and then get it setup in Appflow. At the end of this walkthrough:

- the web application will be setup in Appflow
- each new Android application build will pull the latest version of the web application from Appflow
- the Android application will have a Portal setup pointing to the web application files.
- The web application will be setup in Appflow.
- Each new Android application build will pull the latest version of the web application from Appflow.
- The Android application will have a Portal setup pointing to the web application files.

## 1. Create a capacitor config

Expand All @@ -33,9 +33,9 @@ Create a `capacitor.config.json` file to the root of your web project. We will n

These configuration values are required for web applications added to Appflow.

- `appId`, a unique id that you provide to your web application
- `appName`
- `webDir`, the directory where your compiled web code will be placed
- `appId`: a unique id that you provide to your web application
- `appName`: the name of your web application
- `webDir`: the directory where your compiled web code will be placed

:::note
There are many options that you can provide to a Capacitor configuration file we will only need a few to get started. These options are defined in the [config schema](https://capacitorjs.com/docs/config#schema).
Expand All @@ -45,7 +45,7 @@ There are many options that you can provide to a Capacitor configuration file we

Now that we have the application source configured we will need to add it to Appflow. Appflow can be used for deploying the web application into the Portal later using Live Updates.

During the Native App build process the most recent build of the web application will be used to seed the Portal, and then after the Native App deployment every subsequent build can be deployed as an over the air Live update.
During the Native App build process the most recent build of the web application will be used to seed the Portal, and then after the Native App deployment every subsequent build can be deployed as an over the air Live Update.

### Connect the repo

Expand All @@ -56,13 +56,13 @@ In the upper right hand corner you will be able to select `Import existing app`.
<em><img src={useBaseUrl("/img/start-by-adding-an-app-thumbnail.webp")} data-zoom-src={useBaseUrl("/img/start-by-adding-an-app.webp")} width="50%"/></em>
<em><img src={useBaseUrl("/img/import-existing-app-thumbnail.webp")} data-zoom-src={useBaseUrl("/img/import-existing-app.webp")} width="50%"/></em>

- Provide an `App Name`. Most likely using the same you provided in the `capacitor.config.json` file in the previous step.
- Provide an `App Name`. Most likely using the same you provided in the `capacitor.config.json` file in the previous step
- `Capacitor`, as the mobile architecture
- Choose your git host. In this example we have selected `Github`

### Web application builds

After the app has been created you will want to go to the `Builds` page. This is where you will create new builds and see previous builds. Anytime you want to deploy a new version of the web application you will need to create a build from this screen or by using the Ionic Cloud CLI (which we will cover later).
After the app has been created you will want to go to the `Builds` page. This is where you will create new builds and see previous builds. Anytime you want to deploy a new version of the web application you will need to create a build from this screen or by using the [Ionic Cloud CLI](https://ionic.io/docs/appflow/cli/overview).

<em style={{
textAlign: 'center',
Expand Down Expand Up @@ -92,11 +92,15 @@ When creating a new build there are a few values that we need to change on the i

## 3. Setup local dev environment

### Create a Personal Access Token
### Install the Portals CLI

Now that we have the web application all setup in Appflow and built we need to get our local environment set up to be able to pull it from Appflow.

Now that we have the web application all setup in Appflow and built we need to get our local environment setup to be able to pull it from Appflow.
The first step in setting up our local environment is [installing the Portals CLI](../cli/overview.md) within your local dev environment. This CLI will allow us to interact with Appflow programmatically, so that we can pull the latest Build files when building the Native App.

The first step in setting up our local environment is [generating a personal access token](https://dashboard.ionicframework.com/settings/personal-access-tokens).
### Create a Personal Access Token

You will need to [generate a personal access token](https://dashboard.ionicframework.com/settings/personal-access-tokens) in order to pull down Build files using the Portals CLI.

This is done from `Personal Settings` in the `Personal Access Token` tab.

Expand All @@ -113,31 +117,21 @@ Click the `Generate new token` button. While creating the token it is a best pra
After the token is generated you will need to copy it to clipboard because it will be required for the next step. Usually the token follows the format of `ion_XXXXXXXXXXXXX`.
:::

### Create a cloud configuration file

Now create a yaml configuration file in your native project. This file will be used to authenticate against Appflow for your cloud interactions. Place this file in the `app` directory for your project in the same location as your module level `build.gradle` file. It will be referenced by a build script in your native application.

```yaml title=.ionic-cloud.yaml
TOKEN: ion_XXXXXXXXXXXXX
```

:::note
Be sure to set this to ignore in your `.gitignore` [Learn more about the configuration file.](https://ionic.io/docs/appflow/cli/overview#authentication)

:::

### Install the Ionic Cloud CLI
### Create a sync configuration file

Install the Ionic Cloud CLI within your local dev environment. This CLI will allow us to interact with Appflow programmatically. So that we can pull the latest Build files during native builds.
(https://ionic.io/docs/appflow/cli/overview)
Now create a yaml configuration file in your native project. This file will be used to define the web application to download from Appflow, and where to place it, when running the `portals sync` command. Place this file in the `app` directory for your project in the same location as your module level `build.gradle` file. It will be referenced by a build script in your native application.

```bash
(export IONIC_CLOUD_VERSION=0.7.0; curl -sL https://ionic.io/get-ionic-cloud-cli | bash)
```yaml title=".portals.yaml"
sync:
- app-id: 11a0971f
channel: production
directory-name: src/main/assets/featured_products
token: ion_XXXXXXXXXXXXX
```

### Create web application download script
### Sync Appflow at build time

The last step in setting up the local environment is adding a script to the project in Gradle so that it will download the latest web application build from Appflow every time the Android application is built.
The last step in setting up the local environment is adding a script to the project in Gradle so that it will run the `portals sync` CLI command to download the latest web application build from Appflow every time the Android application is built.

Open Android Studio and place the following script at the bottom of your module Gradle script.
<em style={{
Expand All @@ -147,96 +141,40 @@ Open Android Studio and place the following script at the bottom of your module
<img src={useBaseUrl("/img/android-run-script-thumbnail.webp")} data-zoom-src={useBaseUrl("/img/android-run-script.webp")} width="75%"/>
</em>

The scripts are slightly different depending on if you are building on a Windows or *nix based system.

<Tabs
defaultValue="nix"
defaultValue="gv"
values={[
{ label: 'MacOS/Linux', value: 'nix', },
{ label: 'Windows', value: 'win', },
{ label: 'Groovy', value: 'gv', },
{ label: 'Kotlin', value: 'kt', },
]}>
<TabItem value="nix">
<TabItem value="gv">

```groovy title=build.gradle
```groovy title="build.gradle"
// Make the preBuild task depend on syncPortals so it runs every build
preBuild.dependsOn 'syncPortals'

// ...

// Make the preBuild task depend on getLiveUpdate so it runs every build
preBuild.dependsOn 'getLiveUpdate'

tasks.register('getLiveUpdate') {
tasks.register('syncPortals') {
doLast {
String appId = "0ee57266"
String channel = "PRODUCTION"
String portalName = "MY_FIRST_PORTAL"

String assetPath = rootDir.getPath() + '/app/src/main/assets/' + portalName
if (new File(assetPath).exists()) {
// If the web app already exists, replace with fresh download
project.exec {
commandLine 'rm', '-rf', assetPath
}
project.exec {
commandLine 'mkdir', '-p', assetPath
}
} else {
project.exec {
commandLine 'mkdir', '-p', assetPath
}
}

project.exec {
commandLine 'ionic-cloud', 'live-update', 'download', '--config=.ionic-cloud.yaml', '--app-id', appId, '--channel-name', channel, '--zip-name', portalName + '.zip'
}
project.exec {
commandLine 'unzip', portalName + '.zip', '-d', assetPath
}
project.exec {
commandLine 'rm', portalName + '.zip'
commandLine 'portals', 'sync'
Copy link
Member

@Steven0351 Steven0351 Apr 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This still needs to know the location of the asset path:

commandLine 'portals', 'sync', '--destination', assetPath

Also, I'm pretty sure that the CLI isn't going to be picked up in the PATH by android studio, so you'd still need to do:

commandLine 'cmd', '/c', 'portals', 'sync', '--destination', assetPath

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does through .portals.yaml:

 - app-id: 11a0971f
   channel: production
   directory-name: src/main/assets/featured_products

Copy link
Member

@Steven0351 Steven0351 Apr 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless someone has tested on both a mac and windows machine otherwise. I know it doesn't show up in the PATH on Mac during my testing on an M-series machine.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have it working in another app. I do have it set on the PATH though, maybe I should call that out.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does through .portals.yaml:

 - app-id: 11a0971f
   channel: production
   directory-name: src/main/assets/featured_products

That's not really a portable example between iOS and android though. That would require the start dir on iOS be "src/main/assets/featured_products" if you're using the same config between ios and android

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is your portals cli located on your machine? Because from what I experienced if it is not in a folder that is part of the default macOS $PATH then it will not get picked up because of how the JVM forks. I was unable under any circumstances able to get it to pick up a $PATH environment variable that I set either when running the gradle task directly or through Android Studio. So, I feel like when people read this:

:::note
The Portals CLI must be registered as part of the `PATH` to run this command successfully.
:::

That they will think they can manipulate the PATH environment variable to get it to pick up, when it probably won't.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting, I just added it to my PATH in .zshrc:

export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jbr/Contents/Home
export VOLTA_HOME="$HOME/.volta"
export PORTALS_PATH="/opt/homebrew/opt/portals"
export STUDIO_PATH="/Applications/Android Studio.app/Contents/MacOS"
export PATH="$VOLTA_HOME/bin:$PORTALS_PATH:$STUDIO_PATH:$PATH"

Copy link
Member

@Steven0351 Steven0351 Apr 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, are you opening Android Studio via the command line? Essentially the same problem should occur as with Xcode, in that it respects no PATH other than what is in /etc/paths

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. However, I am more than happy to suggest something else instead of the note, just not sure what it would be.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey so I tested fresh on Mac and Windows and both were picked up fine by Android studio on both machines. I installed via Brew on Mac and when I restarted Android Studio it was picking it up, and on Windows I followed the instructions on the download page for the Portals CLI and put it in a folder in my user dir, and added that to my system PATH in Windows, then restarted Android Studio and it finds it.

}
}
}
```

</TabItem>
<TabItem value="win">

```java title=build.gradle

// ...
<TabItem value="kt">

// Make the preBuild task depend on getLiveUpdate so it runs every build
preBuild.dependsOn 'getLiveUpdate'
```kotlin title="build.gradle.kts"
// Make the preBuild task depend on syncPortals so it runs every build
tasks.named("preBuild") {
dependsOn("syncPortals")
}

tasks.register('getLiveUpdate') {
tasks.register("syncPortals") {
doLast {
String appId = "0ee57266"
String channel = "PRODUCTION"
String portalName = "MY_FIRST_PORTAL"

String assetPath = rootDir.getPath() + '\\app\\src\\main\\assets\\' + portalName
if (new File(assetPath).exists()) {
// If the web app already exists, replace with fresh download
project.exec {
commandLine 'cmd', '/c', 'rm', '-r', assetPath
}
project.exec {
commandLine 'cmd', '/c', 'mkdir', assetPath
}
} else {
project.exec {
commandLine 'cmd', '/c', 'mkdir', assetPath
}
}

project.exec {
commandLine 'cmd', '/c', 'ionic-cloud', 'live-update', 'download', '--config=".ionic-cloud.yaml"', '--app-id', appId, '--channel-name', channel, '--zip-name', portalName + '.zip'
}
project.exec {
commandLine 'cmd', '/c', 'unzip', portalName + '.zip', '-d', assetPath
}
project.exec {
commandLine 'cmd', '/c', 'rm', portalName + '.zip'
exec {
commandLine("portals", "sync")
}
}
}
Expand All @@ -245,11 +183,9 @@ tasks.register('getLiveUpdate') {
</TabItem>
</Tabs>

There are a few variables that you will need to setup at the beginning of script.

- `APP_ID` - Web application id from Appflow
- `CHANNEL` - Live update distribution channel.
- `PORTAL_NAME` - Choose a name for the portal, no spaces.
:::note
The Portals CLI must be registered as part of the `PATH` to run this command successfully.
:::

## 4. Setup Portals in your Android App

Expand Down
Loading
Loading