Debug for mobile

When you're building a Microsoft Teams app that includes a tab, bot, or message extension, you must debug your app to know how the app functions on both Android and iOS Microsoft Teams mobile clients. For more information, see debug your Teams app locally.

See the following video to learn how to debug your Teams app in mobile clients:

Debug your tab app

To debug your tab app follow these steps:

Visual Studio Code

You can view the project folders and files under Explorer in the Microsoft Visual Studio Code.

1. Add Start local tunnel after Validate prerequisites in the task.json file to make the tab app accessible on the mobile client.

2. Add the following code after the property dependsOrder in the task.json file.

   {
     "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

   • To preview the tab app only in mobile client, set the value for access property to private.
   • When the dev tunnel access value is set to private, the tab app cannot be displayed within an iframe on the web client. The login page is hosted on login.microsoftonline.com, which has the X-FRAME-Options header set to DENY.
   • To preview the tab app on the mobile client and debug it on web clients, set the access value to public. Any user with the app's URL can visit the tab.

3. Remove TAB_DOMAIN and TAB_ENDPOINT from the teamsapp.local.yml file.

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

4. If you're using React, add the configuration WDS_SOCKET_PORT=0 in teamsapp.local.yml file to activate hot reloading while debugging in 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 
   

5. Run the deployed app

   1. Open the debug panel (Ctrl+Shift+D or View > Run) from Visual Studio Code.
   2. Select Launch Remote in Teams (Edge) from the launch configuration dropdown.
   3. Select the Start debugging (F5) button.

   

   4. You'll be prompted to upload a custom app into Teams. Select Add.

      

      The app opens as a personal tab.

      

Command Line

1. Go to ngrok and sign up for a free account or log into your existing account.

2. After you've signed in, from the left pane select Your Authtoken.

3. Copy the value of your Authtoken.

4. Run the ngrok.exe file.

5. Run the command ngrok http https://localhost:53000 --authtoken=<your-personal-ngrok-authtoken> to start the local tunnel service.

6. In the env/.env.local file, update the values for TAB_DOMAIN and TAB_ENDPOINT.

    TAB_DOMAIN=sample-ngrok-id.ngrok.io 
    TAB_ENDPOINT=https://sample-ngrok-id.ngrok.io
   

7. Run the following commands in your project directory:

   1. teamsfx provision --env local
   2. teamsfx deploy --env local
   3. teamsfx preview --env local

Test your tab app on mobile client

1. To find the previewing app, open Teams on your mobile device and select More.

   

   Note

   If a you have debugged the app previously, it's recommended to clear the cache on the mobile device to ensure immediate app synchronization. After clearing the cache, the app takes some time to sync.

   iOS

   To clear the Teams app data, go to Settings > Teams > Clear App Data.

   

   Android

   To clear the Teams app data, go to Teams > Settings > Data and storage > Clear app data > Clear data.

   

2. If you're accessing the dev tunnel for the first time, sign in to Microsoft 365 account and select continue.

   

   Note

   You need to login only once per device, and every time you install the app you need to confirm the anti-phishing page.

3. Your first mobile tab app is created.

   

4. For Android devices, use DevTools to debug your tab while it's running.

Test your bot app on mobile client

1. To test your bot in mobile client, follow the steps listed in Test your tab app on mobile client for your bot.

   Note

   If a you have debugged the bot app previously and the app manifest (previously called Teams app manifest) file is changed, we recommend to clear the cache on the mobile device to ensure immediate app synchronization. After clearing the cache, the app takes some time to sync.

   iOS

   To clear the Teams app data, go to Settings > Teams > Clear App Data.

   

   Android

   To clear the Teams app data, go to Teams > Settings > Data and storage > Clear app data > Clear data.

   

2. Your first mobile bot app is created.