ZZZ ‐ [Archived] ‐ Run and debug your Teams application on iOS or Android client

Important

Content in this document has been moved to Teams platform documentation. Please do not refer to or update this document.

Run and debug your Teams application on iOS or Android client.

Please follow the instructions in this tutorial to debug your bot or message extension apps or preview your tab application on mobile devices.

Steps for testing a tab app on mobile client

1. Run the Teams tab app locally

   • For VSCode:

     • Update .vscode/task.json, add Start local tunnel task to make the tab app accessible on the mobile client.

       {
           "version": "2.0.0",
           "tasks": [
               {
                   "label": "Start Teams App Locally",
                   "dependsOn": [
                       "Validate prerequisites",
                       "Start local tunnel", // Add this line
                       "Provision",
                       "Deploy",
                       "Start application"
                   ],
                   "dependsOrder": "sequence"
               },
               {
                   // Add this task
                   "label": "Start local tunnel",
                   "type": "teamsfx",
                   "command": "debug-start-local-tunnel",
                   "args": {
                       "type": "dev-tunnel",
                       "ports": [
                           {
                               "portNumber": 53000,
                               "protocol": "https",
                               "access": "private",
                               "writeToEnvironmentFile": {
                                   "endpoint": "TAB_ENDPOINT",
                                   "domain": "TAB_DOMAIN"
                               }
                           }
                       ],
                       "env": "local"
                   },
                   "isBackground": true,
                   "problemMatcher": "$teamsfx-local-tunnel-watch"
               }
           ]
       }

       Note: When the access of a tab app is set to private, it can only be previewed on the mobile client. However, if you want to preview the app on the mobile client and debug it on web clients, you need to set the access level to public. It's worth noting that public access raises safety concerns since the tab app can be visited by anyone who knows the app's URL.

     • Update teamsapp.local.yml, remove the following action to avoid setting the TAB_DPMAIN and TAB_ENDPOINT in the env file.

       - uses: script
         with:
           run:
             echo "::set-teamsfx-env TAB_DOMAIN=localhost:53000";
             echo "::set-teamsfx-env TAB_ENDPOINT=https://localhost:53000"; 

     • If you're using React, update teamsapp.local.yml, add the configuration WDS_SOCKET_PORT=0 to activate hot reloading while debugging React after utilizing the tunnel service.

       - uses: file/createOrUpdateEnvironmentFile 
         with: 
           target: ./.localConfigs
           envs: 
             BROWSER: none 
             HTTPS: true 
             PORT: 53000 
             SSL_CRT_FILE: ${{SSL_CRT_FILE}} 
             SSL_KEY_FILE: ${{SSL_KEY_FILE}} 
             REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} 
             REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html 
             WDS_SOCKET_PORT: 0 

     • Use the Run and Debug Activity Panel in Visual Studio Code and click the Debug in Teams green arrow button.

   • For CLI:
     • Install dev tunnel cli.
     • Login with your M365 Account using the command devtunnel user login.
     • Start your local tunnel service by running the command devtunnel host -p 3978 --protocol http --allow-anonymous.
     • In the env/.env.local file, fill in the values for BOT_DOMAIN and BOT_ENDPOINT with your dev tunnel URL.

       TAB_DOMAIN=sample-id-3978.devtunnels.ms
       TAB_ENDPOINT=https://sample-id-3978.devtunnels.ms
       

     • Executing the command teamsfx provision --env local in your project directory.
     • Executing the command teamsfx deploy --env local in your project directory.
     • Executing the command teamsfx preview --env local in your project directory.

2. Open the sideloading URL and install the app in the Teams website as usual.

   

   Note: When the dev tunnel access is set to private, the tab app cannot be displayed within an iframe on the web client. It is because its login page is hosted on "login.microsoftonline.com", which has the X-FRAME-Options header set to DENY. If you want to preview the app on the mobile client and debug it on web clients, you need to set the access level to public. It's worth noting that public access raises safety concerns since the tab app can be visited by anyone who knows the app's URL.

   

3. Open Teams on your mobile device and click "More" to find the previewing app.

   

   Note: If a user has previously debugged the app, it is advisable for them to clear the cache on their mobile device to ensure immediate app synchronization. After clearing the cache, it may take some time for the app to sync.

   On iOS devices, the Teams app data can be cleared by navigating to Settings -> Teams -> Clear App Data.

   

   For android devices, the Teams app data can be cleared by navigating to Teams->Settings->Data and storage->Clear app data->Clear data

   

4. If you are accessing the dev tunnel for the first time, you will need to sign in with your M365 account and confirm the anti-phishing page.

   

   Note: The login process should only be required once per device, and confirmation of the anti-phishing page must be completed after every installation of the app.

5. Show a mobile friendly tab app.

   

6. For Android devices, you can use DevTools to debug your tab while it is running.

Steps for debugging a Teams bot app on mobile client

1. Start a Bot App in VSC / CLI Same to the current Teams Toolkit behavior.

2. Open the sideloading URL and install the app in the Teams website as usual.

3. Open Teams on your mobile device and click "More" to find the previewing app.

   

   Note: If a user has previously debugged the bot app and the Team app manifest file is changes, it is advisable for them to clear the cache on their mobile device to ensure immediate app synchronization. After clearing the cache, it may take some time for the app to sync.

   On iOS devices, the Teams app data can be cleared by navigating to Settings -> Teams -> Clear App Data.

   

   For android devices, the Teams app data can be cleared by navigating to Teams->Settings->Data and storage->Clear app data->Clear data

   

4. Debug the bot app on your mobile.