Launch forms via odkcollect:// links, with entity preselection

.github/workflows/custom_release.yml

@@ -0,0 +1,44 @@
+# Workflow to deploy custom builds on ODK Collect
+
+name: 🔧 Build and Release
+
+on:
+  release:
+    types: [published]
+  # Allow manual trigger (workflow_dispatch)
+  workflow_dispatch:
+
+jobs:
+  build_upload_apk:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    container:
+        image: docker.io/cimg/android:2023.10.1
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Add Robolectric Deps
+        run: ./download-robolectric-deps.sh
+
+      - name: Compile Code
+        run: ./gradlew assembleDebug
+
+      - name: Install Github CLI
+        run: |
+          sudo apt update
+          sudo apt install --no-install-recommends -y gh
+
+      - name: Build & Upload APK
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ./gradlew assembleSelfSignedRelease
+
+          apk_path=$(find ./collect_app/build/outputs/apk/selfSignedRelease -name '*.apk' -type f)
+          echo "Generated APK file: ${apk_path}"
+
+          gh release upload ${{ github.event.release.tag_name }} "${apk_path}"

collect_app/src/main/AndroidManifest.xml

@@ -97,7 +97,21 @@ the specific language governing permissions and limitations under the License.
         </provider>
 
         <activity
-            android:name=".activities.FirstLaunchActivity">
+            android:name=".activities.FirstLaunchActivity"
+            android:exported="true">
+
+            <!--
+             This intent-filter enables the launching of FirstLaunchActivity
+             via in-browser links in the format
+             "odkcollect://project/configuration?data=<settings-data>"
+             to set up the project.
+           -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW"/>
+                <data android:scheme="odkcollect" android:host="project" />
+                <category android:name="android.intent.category.DEFAULT"/>
+                <category android:name="android.intent.category.BROWSABLE"/>
+            </intent-filter>
         </activity>
 
         <activity
@@ -324,6 +338,19 @@ the specific language governing permissions and limitations under the License.
                 <data android:mimeType="vnd.android.cursor.item/vnd.odk.form" />
                 <data android:mimeType="vnd.android.cursor.item/vnd.odk.instance" />
             </intent-filter>
+
+            <!--
+              This intent-filter enables the launching of FormUriActivity
+              via in-browser links in the format
+              "odkcollect://form/<form_id>" (see FormUriActivity for details).
+              It leads to open the form with the given form id with pre filled forms
+            -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW"/>
+                <data android:scheme="odkcollect" android:host="form" />
+                <category android:name="android.intent.category.DEFAULT"/>
+                <category android:name="android.intent.category.BROWSABLE"/>
+            </intent-filter>
         </activity>
 
     </application>

collect_app/src/main/java/org/odk/collect/android/activities/FirstLaunchActivity.kt

@@ -14,8 +14,11 @@ import org.odk.collect.android.databinding.FirstLaunchLayoutBinding
 import org.odk.collect.android.injection.DaggerUtils
 import org.odk.collect.android.mainmenu.MainMenuActivity
 import org.odk.collect.android.projects.ManualProjectCreatorDialog
+import org.odk.collect.android.projects.ProjectCreator
 import org.odk.collect.android.projects.ProjectsDataService
 import org.odk.collect.android.projects.QrCodeProjectCreatorDialog
+import org.odk.collect.android.projects.SettingsConnectionMatcher
+import org.odk.collect.android.utilities.ProjectSetupHelper
 import org.odk.collect.android.version.VersionInformation
 import org.odk.collect.androidshared.system.ContextUtils.getThemeAttributeValue
 import org.odk.collect.androidshared.ui.DialogFragmentUtils
@@ -25,6 +28,7 @@ import org.odk.collect.projects.Project
 import org.odk.collect.projects.ProjectsRepository
 import org.odk.collect.settings.SettingsProvider
 import org.odk.collect.strings.localization.LocalizedActivity
+import timber.log.Timber
 import javax.inject.Inject
 
 class FirstLaunchActivity : LocalizedActivity() {
@@ -41,6 +45,9 @@ class FirstLaunchActivity : LocalizedActivity() {
     @Inject
     lateinit var settingsProvider: SettingsProvider
 
+    @Inject
+    lateinit var projectCreator: ProjectCreator
+
     @Inject
     lateinit var scheduler: Scheduler
 
@@ -102,14 +109,54 @@ class FirstLaunchActivity : LocalizedActivity() {
                 text = SpannableStringBuilder()
                     .append(getString(org.odk.collect.strings.R.string.dont_have_project))
                     .append(" ")
-                    .color(getThemeAttributeValue(context, com.google.android.material.R.attr.colorAccent)) {
+                    .color(
+                        getThemeAttributeValue(
+                            context,
+                            com.google.android.material.R.attr.colorAccent
+                        )
+                    ) {
                         append(getString(org.odk.collect.strings.R.string.try_demo))
                     }
 
                 setOnClickListener {
                     viewModel.tryDemo()
                 }
             }
+
+            // When the FirstLaunchActivity is started via a browsable link in
+            // the format "odkcollect://project/configuration?data=<settings-data>",
+            // setup project automatically if data is valid
+            initiateProjectSetUp()
+        }
+    }
+
+    /**
+     * Method to initiate project setup from a URI.
+     * When the FirstLaunchActivity is started via a browsable link in
+     * the format "odkcollect://project/configuration?data=<settings-data>",
+     * setup project automatically if data is valid
+     */
+    private fun initiateProjectSetUp() {
+        try {
+            val uri = intent.data
+
+            if (uri?.scheme != "odkcollect" || uri.host != "project") return
+
+            val segment = uri.pathSegments.firstOrNull()
+
+            if (segment != "configuration") return
+
+            val helper = ProjectSetupHelper(
+                this,
+                SettingsConnectionMatcher(projectsRepository, settingsProvider),
+                projectCreator,
+                projectsDataService
+            )
+
+            helper.initiateSetup(uri)
+
+        } catch (e: Exception) {
+            Timber.e(e)
         }
     }
 }

collect_app/src/main/java/org/odk/collect/android/analytics/AnalyticsEvents.kt

@@ -73,6 +73,11 @@ object AnalyticsEvents {
      */
     const val QR_CREATE_PROJECT = "ProjectCreateQR"
 
+    /**
+     * Tracks how often projects are created using deeplink.
+     */
+    const val DEEPLINK_CREATE_PROJECT = "ProjectCreateDeeplink"
+
     /**
      * Tracks how often projects are created by manually entering details.
      */