Skip to main content

FAQ

MiniApp Basics​

Q: What are MiniApps?​

A: MiniApps are web applications developed using standard web technologies. They run within the Woven City App, offering features like Seamless login and notifications.

Q: Why MiniApps?​

A: MiniApps are preferred for their easy development, distribution through Woven City App (which is the main touch point for users in the Woven City), and built-in capabilities that abstract work like login and notifications.

Q: How can I migrate my existing web app to be a MiniApp?​

A: First of all, as long as your web app is responsive to fit mobile screen sizes, then your web app is already a MiniApp! You can immediately submit the URL in the MiniApp Tab of Woven City App Tools.

We also provide a MiniApp SDK to help you integrate with the Woven City App features, but using the SDK is optional and depends on your use case. If you want to use features like Seamless login or notifications, then you can integrate the MiniApp SDK as explained in this documentation.

Q: How to develop a MiniApp?​

A: You can use any web framework to develop your MiniApp, such as React, Angular, Vue, or even plain HTML/CSS/JS. The only requirement is that your MiniApp must be a web application that fits mobile devices screen sizes. You can host your MiniApp on any web server and submit the URL in the MiniApp Tab of Woven City App Tools.

We also provide a MiniApp SDK to help you integrate with the Woven City App features, but using the SDK is optional and depends on your use case. If you want to use features like Seamless login or notifications, then you can integrate the MiniApp SDK as explained in this documentation.

Q: What is the Woven City App?​

A: Woven City App is a touch point with users in the city, containing features like feed, chat, and the MiniApp platform where residents can use multiple MiniApps provided by the city.

Q: How to install the Woven City App?​

A: You install the Woven City App from: https://app.woven-city.toyota.

Let us know if you require a specific version/env of the Woven City App on Woven City App Chat feature through the MiniApp Explorer Project.

There are two login types: SSO which gives you direct access to the Woven City App features, and username+password login where you can use any email addresses for testing and having multiple accounts (requires approval from the Woven City App team on Woven City App Chat feature through the MiniApp Explorer Project).

Q: So we call it Mini App, mini-app, miniapp or MiniApp?​

A: The platform is called "MiniApp Platform", the apps themselves are "MiniApps", and it's "Woven App" or "Woven City App". For service names (hostname, urls etc.): we use "mini-app" and "woven-app".

Q: What is the flow to have my MiniApp running on top of the Woven City App?​

A:

  1. Request a project in Inventor Garage Portal.
  2. Open Woven City App Tools within the project.
  3. Create a MiniApp version by putting the URL of your MiniApp in the MiniApp Tab of Woven City App Tools and saving it.

Q: Can MiniApps be native iOS/Android/Windows/macOS/Linux apps?​

A: No, MiniApps are only web apps for now. If you have a use case for native apps, share it with us on Woven City App Chat feature through the MiniApp Explorer Project.

Q: Do you support native APIs like BLE, NFC and camera?​

A: We don't provide direct native API support. MiniApps can use browser APIs supported by the WebView (Chromium-based on Android, WebKit-based on iOS).

Q: Do you support location APIs?​

A: Yes, through standard geolocation APIs provided by the WebView. Enhanced location APIs are planned for the future.

Q: Are MiniApps supported on both Woven City App iOS version and Android version?​

A: We support both Android and iOS versions of Woven City App.

Woven City App Tools​

Q: How to upload MiniApp zip file?​

A: We don't currently support uploading zip files. Deploy your MiniApp yourself (e.g., using Firebase Hosting for non confidential apps or your own in-house AWS S3 and CloudFront setup) and submit the URL in the MiniApp Tab of Woven City App Tools.

If you struggle with that let us know on Woven City App Chat feature through the MiniApp Explorer Project and we will support you with a special option.

Q: Inventor Garage Portal vs Woven City App Tools?​

A:

  • Inventor Garage Portal is an interface for managing projects and related components.
  • Woven City App Tools is a sub interface within Inventor Garage Portal for managing Woven City App related features such as MiniApps.

Q: I created a project in Inventor Garage Portal but others can't see in Woven City App, why?​

A: By default, projects are only visible to members. To make it visible to others, contact us on Woven City App Chat feature through the MiniApp Explorer Project to request visibility updates.

Soon, we will provide a self-serve option for managing project visibility in the Woven City App Tools.

Q: What happens if I update my project in Inventor Garage Portal? My project will be hidden again from the Woven City App?​

A: No, when a project is updated, the visibility will not be changed.

Q: What happens when I submit the url of my app? Do I need approval or not?​

A: Currently, there's no approval process - it's approved automatically. We plan to implement an approval process in the future.

Q: What do Server-side and Seamless login clients mean?​

A: Both are Keycloak clients but serve different purposes:

  • Server-side Client: A confidential type Keycloak client that comes with a client_id and client_secret. This client is used by your MiniApp's backend to authenticate and access server-side APIs (e.g. chat and notification APIs).

  • Seamless login Client: A client designed specifically for the Seamless login flow. It generates tokens issued by the MiniApp platform. These tokens are validated by your MiniApp backend to authenticate requests from the MiniApp's frontend (i.e. The token's azp claim must include this client's client_id).

Each MiniApp project is linked to one Server-side client and one Seamless login client.

Both clients are automatically created when creating a new MiniApp.

Q: Why can't I access a MiniApp project in Woven City App Tools?​

A: Possible reasons: incorrect project ID or you're not a member of the project.

Q: How can I create a project?​

A: Request project creation on Woven City App Chat feature through the MiniApp Explorer Project, providing project name, description, and member emails.

Q: How can I become a member of a project?​

A: Request membership updates from your project leader. They can add you as a member through the Inventor Garage Portal.

Sandbox and Debugging​

Q: test mode vs live mode?​

A: We currently don't support live and test modes anymore.

Previously, live mode was for public viewing, while test mode was for project members only, accessible from the sandbox page.

Q: I used to have test mode enabled which allow access my own MiniApp in sandbox page and live mode for everyone is this still supported?​

A: No, this is no longer supported.

Q: How to use the sandbox?​

A: Open Woven City App, go to the profile page, click app version 10 times to enable developer mode, then find sandbox inside.

Q: Why can't I access my MiniApp running in localhost in sandbox?​

A: 'Localhost' on your phone refers to the phone itself. To access your computer-hosted MiniApp:

  1. Ensure your phone and computer are on the same network.
  2. Get your computer's local IP address.
  3. Enter http://{YOUR_COMPUTER_LOCAL_IP}:{PORT_WHERE_YOUR_APP_RUNNING} in the Woven City App sandbox.
  4. Click 'Open MiniApp'.

Note: This may not work when using a VPN.

Q: How can I see the Woven City App version? MiniApp Engine version?​

A: Woven City App version is visible on the user profile page. MiniApp Engine version is not currently displayed, but will be added to the same page in the future.

General​

Q: Can I redirect from my MiniApp to another MiniApp?​

A: Yes, it's possible if you know the project_id of the target MiniApp. Use the deeplink: wovenapp://projects/:id/miniapp?param=value

Note: Future updates may include dynamic checks with proper whitelisting. (If you have a use case, please inform us in advance on Woven City App Chat feature through the MiniApp Explorer Project )

Q: Can I redirect from a MiniApp to an external website inside the MiniApp page?​

A: Yes, currently there are no restrictions. The website will open in the same webview.

Note: Future updates may include dynamic checks with proper whitelisting. (If you have a use case, please inform us in advance on Woven City App Chat feature through the MiniApp Explorer Project )

Q: Can I redirect from a MiniApp to an external website in device browser?​

A: No, this is not currently possible. (If you have a use case, please inform us in advance on Woven City App Chat feature through the MiniApp Explorer Project )

Q: Because the Woven City App works without VPN, does this also mean my MiniApp will automatically be accessible without VPN?​

A: Woven City App doesn't require company VPN or corporate network connection. However, this doesn't automatically make your MiniApp accessible without VPN. You need to expose your MiniApp to the internet yourself.

Q: Can we change the exit button style?​

A: No, currently the MiniApp exit button style cannot be changed.

Q: Can we customize the app bar?​

A: The app bar itself cannot be customized, but it can be removed for special teams. The floating exit button will remain in the top right. The app bar can be then developed by your MiniApp code.

You should be able to configure this in the Woven City App Tools when creating a new MiniApp version.

Q: Can we set the app bar to use dark and light mode?​

A: Yes, In case your app supports only light/dark mode you can configure your MiniApp in the Woven City App Tools to force the Runtime Engine to use only dark/light theme.

If you delete this config the Runtime Engine will use the default settings, which means the app bar will follow the device theme.

notification API​

Q: What's the url of the notification inside agora cluster and also outside the cluster?​

A: Our services accessible only through the public URL

Q: What are the things I need to prepare to be able to send notifications?​

A: To send notifications to your MiniApp / project:

  1. Have a project created on Inventor Garage Portal or by MiniApp Platform Team.
  2. Create a MiniApp version which will automatically generate the required Server-side client for you
  3. When prompted, copy and securely store the Server-side client_secret. You can find the Server-side client_id anytime in the Woven City App Tools page for your MiniApp but the client_secret is only shown once during the generation of the client.
warning

When creating a MiniApp for the first time, you'll receive a one-time popup (shown below) displaying your server-side client secret. Copy and store this secret securely, as it will be difficult to retrieve later. Note that these credentials will remain unchanged when you create new versions of your MiniApp.

Q: How to send a notification?​

A: Follow these steps:

  1. Obtain an access token from Keycloak:
curl 'https://id.woven-city.toyota/auth/realms/woven/protocol/openid-connect/token'
-d 'client_id={YOUR_KEYCLOAK_CLIENT_ID}'
-d 'client_secret={YOUR_KEYCLOAK_CLIENT_SECRET}'
-d 'grant_type=client_credentials'
  1. Use this access token to send a request to our notification API
curl -X 'POST' 'https://mini-app-api.lab.woven-city.toyota/mini-app-runtime/v1/notification'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer {ACCESS_TOKEN}'
-d '{
  "project_id": "{YOUR_PROJECT_ID}",
  "payload": { "key1": "value1", "key2": "value2" },
  "title": "any title",
  "app_level_notification_body": "notification that will show inside the app",
  "os_level_notification_body": "notification that will show in the os level",
  "woven_ids": ["{TARGET_USER_KEYCLOAK_ID}"]
}
'

Explanation of fields:

  • project_id: Your project ID
  • payload: A map of key-value pairs (both strings) for any additional data
  • title: the notification title displayed in the OS-level notification only
  • app_level_notification_body: The notification text displayed inside the app's notification panel only
  • os_level_notification_body: The notification text displayed in the OS-level notification (can be used for privacy purposes e.g. not showing sensitive info in the OS-level notification but showing it in the app-level notification when the user opens the app using the app_level_notification_body)
  • woven_ids: Also referred to as Keycloak IDs, these are the IDs of the target users

Q: How to redirect to own MiniApp after user click notification? And how to pass data to own MiniApp after user clicks the notification?​

A: Use the payload field in the notification request body. This payload will be provided to the MiniApp as query parameters in the root path of your MiniApp.

  1. When sending the notification, include a payload in the request body:
{
  "app_level_notification_body": "Hello, App level!",
  "os_level_notification_body": "Hello, OS level!",
  "payload": {
    "key1": "value1",
    "foo": "bar"
  }
}
  1. Inside your MiniApp, access this data using JavaScript:
// Parse the URL to get query parameters
const urlParams = new URLSearchParams(window.location.search);

// Access specific query parameters
const key1Value = urlParams.get("key1");
const fooValue = urlParams.get("foo");

console.log("Value of key1:", key1Value);
console.log("Value of foo:", fooValue);

A: There are two ways to set deeplinks in notifications:

  1. Default Deeplink: If you don't specify any deeplink, the MiniApp engine will automatically set up a deeplink to redirect users to your MiniApp after clicking the notification.

  2. Custom Deeplink: Use the endpoint: /mini-app-runtime/v1/notification/custom_redirect and include a redirect_to in your request body. Example of sending a notification with custom redirect:

curl -X 'POST'
'https://mini-app-api.lab.woven-city.toyota/mini-app-runtime/v1/notification/custom_redirect'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer {ACCESS_TOKEN}'
-d '{
  "project_id": "{YOUR_PROJECT_ID}",
  "payload": { "key1": "value1", "key2": "value2" },
  "title": "any title",
  "app_level_notification_body": "notification that will show inside the app",
  "os_level_notification_body": "notification that will show in the os level",
  "redirect_to": "{your custom url or deeplink here}",
  "woven_ids": ["{TARGET_USER_KEYCLOAK_ID}"]
}
'

Note: Currently, there are no restrictions on the URLs you can use, but in the future, there will be dynamic checks and whitelisting for allowed URLs per MiniApp.

Q: How to make notification not redirect to any where after click?​

A: Use the custom redirect endpoint and set the redirect_to field to an empty string. For example:

curl -X 'POST'
'https://mini-app-api.lab.woven-city.toyota/mini-app-runtime/v1/notification/custom_redirect'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer {ACCESS_TOKEN}'
-d '{
  "project_id": "{YOUR_PROJECT_ID}",
  "payload": { "key1": "value1", "key2": "value2" },
  "title": "any title",
  "app_level_notification_body": "notification that will show inside the app",
  "os_level_notification_body": "notification that will show in the os level",
  "redirect_to": "",
  "woven_ids": ["{TARGET_USER_KEYCLOAK_ID}"]
}
'

Q: Can I send a notification to other MiniApps?​

A: No, it's not possible to send notifications to other MiniApps. You can only send notifications to your own MiniApp.

This is part of the security design:

  • Each project is associated with a confidential type keycloak client (commonly referred to as a Server-side Client).
  • This keycloak client is used to authenticate your requests to send notifications.
  • The system ensures that you can only send notifications to the MiniApp associated with your project.
  • As long as you keep your client_secret secure, no one else can send notifications to your MiniApp.
  • Similarly, you cannot send notifications to other MiniApps.

Q: Can I call the notification endpoint from my MiniApp frontend side?​

A: While it's technically possible, you absolutely should not do this because:

  • Calling the notification endpoint requires using your client_secret.
  • If you include the client_secret in your frontend code, it would be exposed to anyone who can access your MiniApp.
  • This exposure would allow malicious actors to impersonate your MiniApp when interacting with our services.

Key points:

  • DO NOT use the notification endpoint in the client-side code.
  • ONLY use the notification endpoint in your server-side code.
  • Keep your client_secret secure and never expose it in frontend code.

Q: I received a 403 and 401 error when I tried to access the endpoint? Why is that?​

A: This can be because of the following reasons:

  • Access token is invalid
  • Access token is valid but expired
  • Access token is valid and not expired but from a client_id not mapped to your project

To troubleshoot:

  1. Check token validity and expiry:
    • Use the introspect endpoint from Keycloak to validate the token, or
    • Paste your token into jwt.io to check its fields
  2. If the token seems okay, verify your project metadata:
    • Open the MiniApp in the Woven City App Tools
    • Check the Server-side client associated with your project
  3. If the Server-side client in the Woven City App Tools doesn't match the one you're using, or if you're still having issues, reach out to us on Woven City App Chat feature through the MiniApp Explorer Project.

Q: Support multi languages for notification?​

A: We don't provide built-in multi-language support for notifications. You need to handle language localization on your own. Here's a suggested approach:

  1. When a user opens your MiniApp, detect their preferred language:
const userLanguage = window.navigator.language;
  1. Send this language preference to your server and store it associated with the user.
  2. When sending a notification:
  • Retrieve the user's language preference from your db
  • Prepare the notification content in the appropriate language
  • Send the localized notification using our notification API

Remember to handle cases where a language preference isn't set or isn't supported by your app.

Authentication​

Q: How does the Seamless login flow work?​

A: The Seamless login flow works as follows:

  1. The user is already logged into the Woven City App.
  2. When the user opens a MiniApp, the MiniApp Platform:
    • Identifies the MiniApp and retrieves the associated Seamless login client
    • Performs a token exchange, swapping the Woven City App token for a MiniApp token
  3. The exchanged token is provided to the MiniApp when it starts.

To retrieve the exchanged access token in your MiniApp:

import { MiniAppAuthClient } from "@wcm/mini-app-sdk/auth";
const authClient = new MiniAppAuthClient();
await authClient.signInFromWindowLocation();
const access_token = authClient.tokens.accessToken;

Q: How can I enable Seamless login?​

A: Seamless login client required for seamless login is automatically created when creating a new MiniApp but the Seamless login is disabled by default. You can enable it by going to the Woven City App Tools and toggling the Seamless login option.

Once configured, you will see Seamless login enabled in your MiniApp's Woven City App Tools, along with the Seamless login client's client_id.

Q: Do I have to ask the team handling Keycloak to prepare Keycloak clients for me?​

A: No, you don't need to request Keycloak clients manually. Both the Server-side client and Seamless login client are automatically created when you create a new MiniApp version. The client IDs will be visible in your MiniApp Woven City App Tools, and you'll receive the client secret via a one-time popup during creation.

warning

When creating a MiniApp for the first time, you'll receive a one-time popup (shown below) displaying your server-side client secret. Copy and store this secret securely, as it will be difficult to retrieve later. Note that these credentials will remain unchanged when you create new versions of your MiniApp.

Q: What are the things I need to prepare to support Seamless login?​

A:

  1. Ensure you have a project in the Inventor Garage Portal or by MiniApp Platform Team.
  2. Confirm that Seamless login is enabled for your project in the Woven City App Tools.
  3. Use the MiniApp SDK in your MiniApp to retrieve the needed tokens.

Q: What happens if the access token received is expired? How to refresh it?​

A: Two options:

  1. Automatic Refresh:
    • Use const authClient = new MiniAppAuthClient({useAutoRefresh: true});
    • With this setting, your token will be automatically refreshed when needed.
    • You can always get the current access token using: const accessToken = authClient.tokens.accessToken;
  2. Manual Refresh:
    • Use const authClient = new MiniAppAuthClient({useAutoRefresh: false});
    • When you need to refresh the token, use the following API:
curl -X 'POST' 'https://mini-app-api.lab.woven-city.toyota/mini-app-runtime/v2/auth/refresh'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{ "refresh_token": "{YOUR_REFRESH_TOKEN}" }'
  • This endpoint will return a new refresh token, access token, and ID token.
  • For the first refresh, replace {YOUR_REFRESH_TOKEN} with the refresh token you got from: const refreshToken = authClient.tokens.refreshToken;
  • For subsequent refreshes, use the new refresh token you received from the previous refresh call.

Note: When using manual refresh, it's your responsibility to handle token expiration and refreshing. Make sure to securely store and manage your refresh tokens.

Q: How to protect my app to not allow login from fake Woven City Apps? or not allow my MiniApp url to be used by others?​

A: To prevent login from fake Woven City Apps and misuse of your MiniApp URL

  • Use the Seamless login to get token from MiniApp Platform when running your MiniApp.
  • Validate the access token and verify the azp field matches your Seamless login client, as displayed in the Woven City App Tools.

Q: The refresh endpoint is not working. What should I do?​

A: Troubleshoot by:

  1. Checking if the refresh token is valid and not expired
  2. If you using the manual refresh, verifying MiniAppAuthClient configuration (useAutoRefresh should be false)
  3. If issues persist, reach out to us on Woven City App Chat feature through the MiniApp Explorer Project for support

Chat API​

Q: How to send chat message from my server?​

A: The flow for sending chat messages is the same as for regular notifications. You need to get an access token and then use the chat endpoint.

To send a chat message, follow these steps:

  1. First, obtain an access token from Keycloak:
curl -d 'client_id={YOUR_KEYCLOAK_CLIENT_ID}' \
     -d 'client_secret={YOUR_KEYCLOAK_CLIENT_SECRET}' \
     -d 'grant_type=client_credentials' \
    'https://id.woven-city.toyota/auth/realms/woven/protocol/openid-connect/token'
  1. Once you have the access token, use it to send the chat message:
curl -X 'POST' \
  'https://mini-app-api.lab.woven-city.toyota/mini-app-runtime/v1/chat' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -d '{
    "project_id": "{YOUR_PROJECT_ID}",
    "message": "your **message**",
    "woven_ids": ["{TARGET_USER_KEYCLOAK_ID}"]
}'

Explanation of fields:

  • project_id: Your project ID
  • message: The content of your chat message (does not supports markdown formatting)
  • woven_ids: The IDs of the target users (also referred to as Keycloak IDs)

Note:

  • The message field does not supports markdown formatting.
  • Links in the message will be automatically detected and converted to clickable links.
  • Replace {ACCESS_TOKEN} with the token obtained from step 1
  • https://mini-app-api.lab.woven-city.toyota is the base URL for the MiniApp API on production.

Note: Remember to keep your client_secret secure and never expose it in client-side code.

Q: Why does the chat endpoint return 403 and 401?​

A: There are several possible reasons:

  • Access token is missing from the request's authorization header.
  • Access token is invalid
  • Access token is valid but expired
  • Access token is valid and not expired but from a client_id not mapped to your project

To troubleshoot:

  1. Check token validity and expiry:
    • Use the introspect endpoint from Keycloak to validate the token, or
    • Paste your token into jwt.io to check its fields
  2. If the token seems okay, verify your project metadata:
    • Open the MiniApp Woven City App Tools
    • Check the Server-side client_id associated with your project
  3. If the client_id in the Woven City App Tools doesn't match the one you're using, or if you're still having issues, reach out to us on Woven City App Chat feature through the MiniApp Explorer Project.

Q: Why does the chat endpoint return 200, but the user doesn’t receive the notification?​

A: The chat API processes bulk requests to send messages to users. A 200 response indicates that the request was successfully handled, and the authorization check passed. However, you need to parse the API response to identify any users who failed to receive the notification. The response includes a list of such users along with the reasons, which are typically:

  • The recipient hasn't joined your project yet (users must first join your project and accept the necessary agreements to receive notifications)
  • The recipient is a project member (chat notifications cannot be sent to your own project members to maintain proper chat functionality)

Another possible scenario is when you receive a 200 response with no errors in the response payload. In this case, the notification was delivered successfully to the user, but they may have disabled notifications on their end.

Q: Why does the chat say it can't send notifications to members, but at the same time, it can't send messages to users who have joined the project? What’s the difference between a member and a user who has joined the project?​

A:

  • Project Members: These are developers and administrators you've assigned to manage your project. They handle project content and MiniApp-related tasks. Members cannot receive chat notifications as they're part of the project team.
  • Joined Users: This is the process where users opt into the project by following it, signing to the necessary terms, to actively use your MiniApp. Users must:
    1. Find your project in the Woven City App
    2. Click "Join Project"
    3. Accept the necessary agreements

Only after completing these steps can users receive notifications from your MiniApp.

Q: Can I send a chat message to members of the project?​

A: No, you can't. The chat message API is designed for the project to send messages, and members of the project can interact as project and reply using the Woven City App mobile or web version.

Q: If I'm a member of a project and can't send a chat message to myself, how can I test sending a chat message?​

A: You can create as many test users as you need in Keycloak using the username+password login method. Then, log into the Woven City App using these test users. To enable username+password login:

  1. Use a different email to create the test user accounts in keycloak
  2. Request access on Woven City App Chat feature through the MiniApp Explorer Project, explaining that you want to use username+password login for testing and provide the email addresses of the test accounts you've created.
  3. The Woven City App team will then enable access for these test accounts

Q: What are the URLs of the chat message API?​

A: The URLs are the same as for regular notifications, just replace /notification with /chat:

Version and environment compatibility​

Q: What's the difference between MiniApp SDK version and MiniApp Runtime Engine version?​

A: Your MiniApp's SDK version must be compatible with the Runtime Engine version;

  • MiniApp SDK Version refers to the npm package (@wcm/mini-app-sdk) version that you install in your MiniApp project. This is the client-side library that provides the APIs for interacting with the Runtime Engine. npm install @wcm/mini-app-sdk@latest

  • MiniApp Runtime Engine Version refers to the version of the runtime environment provided on top of the SuperApp platform. This is the underlying system that executes your MiniApp and provides the actual implementation of the features your MiniApp uses through the SDK.

Q: How can I get the MiniApp Runtime Engine version?​

A: There are two ways to check the MiniApp Runtime Engine version:

  1. At Runtime (in your MiniApp):
import { getRuntimeEngineMetadata } from "@wcm/mini-app-sdk/runtime-engine";

const metadata = getRuntimeEngineMetadata();
console.log(metadata.miniappPlatformVersion); // e.g., "1.0.0"
  1. In the SuperApp: Navigate to Settings → Woven City App section. The MiniApp Runtime Engine version is listed as MiniApp Platform Version.

Q: How to use different environments (dev/stage/prod)?​

A: By default, this documentation uses production URLs. Before considering a different environment for any special case, first ensure you have access to the corresponding Woven City App environment. Once confirmed, you'll need to make the following changes in your implementation:

  1. MiniApp Platform APIs:

Base URLs per environment:

Deeplinks URLs per environment:

  • Production: wovenapp://projects/:id/miniapp?param=value
  • Staging: wovenappstaging://projects/:id/miniapp?param=value
  • Development: wovenappdev://projects/:id/miniapp?param=value
  1. MiniApp SDK Configuration:

When using SDK features like seamless login, configure the correct environment:

export const authClient = new MiniAppAuthClient({ env: "stage" }); // "prod", "stage", or "dev"

OpenTelemetry Integration​

Q: Why do I get 403 or 401 errors when registering OpenTelemetry?​

A: These errors typically occur when there are issues with the access token used during OpenTelemetry registration. To troubleshoot:

  • Verify you're using the correct access token from the seamless login:
authClient.signInFromWindowLocation().then(() => {
  // Make sure this token is valid
  otel.registerOTel(authClient.tokens.accessToken);
});
  • Check if the token has expired - you may need to refresh it:
authClient.addEventListener("token-refreshed", () => {
  otel.unregisterOTel();
  otel.registerOTel(authClient.tokens.accessToken);
});

Q: I've register Otel but don't see any data in Grafana or network requests. What's wrong?​

A: If you're not seeing any telemetry data, check these common issues:

  • Verify you're using the correct access token from the seamless login:
authClient.signInFromWindowLocation().then(() => {
  // Make sure this token is valid
  otel.registerOTel(authClient.tokens.accessToken);
});
  • Check if the token has expired - you may need to refresh it:
authClient.addEventListener("token-refreshed", () => {
  otel.unregisterOTel();
  otel.registerOTel(authClient.tokens.accessToken);
});
  • Verify OpenTelemetry registration was successful:
otel
  .registerOTel(authClient.tokens.accessToken)
  .then(() => {
    console.log("OpenTelemetry registration successful");
  })
  .catch((error) => {
    console.error("OpenTelemetry registration failed:", error);
  });
  • Ensure you're using the correct environment configuration:
export const otel = new MiniAppOTel({
  serviceName: `your-service-name`,
  env: "stage", // Make sure this matches your target environment (by default prod)
});

Q: The data appears in the vconsole network tab but not in Grafana. What should I check?​

A: There could be several reasons:

  • You might be looking at the wrong Grafana instance. Verify you're using the correct URL based on your environment:

  • Make sure you're looking at the right time range in Grafana - data might be appearing outside your current view

  • Verify you're using the correct service name in your queries - it should match the serviceName you provided in the MiniApp OTel configuration