Description

Message Bridge creates a communication between a website and a browser. It sends and receives messages that conform to our Messaging standard (eg: it's not a new format!)

• Related Privacy Configuration feature file
• Message formats: "Messaging Schema"

Integration guide

Step 1: add messageSecret to $USER_PREFERENCES$

This feature requires the following to be serialized into $USER_PREFERENCES$.

• "messageSecret": "<some uuid>"

Without this, the bridge will refuse to be installed.

Example:

{
    "...": "...",
    "messageSecret": ""
}
Copy

Step 2: Enable in remote config

Using the method of your choice, generate a remote config file that has the bridge feature enabled + some feature & domain combinations.

For example, to enable aiChat on duckduckgo.com domains - you would place the following override in the relevant platform file. This is how the per-domain restrictions are enforced in the JavaScript layer.

{
    "features": {
        "...": "...",
        "messageBridge": {
            "state": "enabled",
            "settings": {
                "aiChat": "disabled",
                "domains": [
                    {
                        "domain": "duckduckgo.com",
                        "patchSettings": [
                            {
                                "op": "replace",
                                "path": "/aiChat",
                                "value": "enabled"
                            }
                        ]
                    }
                ]
            }
        }
    }
}
Copy

NOTE: Native platforms should continue to verify the sending domain when any messages are received.

Example

In a domain where the bridge is enabled, the following API becomes available to the page.

const bridge = navigator.duckduckgo?.createMessageBridge?.('exampleFeature');
bridge.notify('pixel');
Copy

That notify ^ call will result in a "NotificationMessage" being sent to the 'native' layer.

{
    "context": "contentScopeScriptsIsolated",
    "featureName": "exampleFeature",
    "method": "pixel"
}
Copy

Likewise with Requests and Subscriptions - as far as the 'native' side is concerned, they are handled with the same Messaging Schema types.

---

Troubleshooting

Missing MessageName Debugging

If you see missing 'messageName' in the browser debug console:

This means the feature you're expecting to run isn't running.

Troubleshooting Steps

1. Check that the feature is enabled in the config (see remote config debugging).
2. Verify platform parameters allow the feature.
3. Check that the injected script is correct (see build-and-troubleshooting.md for verification steps).
4. Verify message handlers are properly registered in the native app.
5. Check that the messaging bridge is correctly initialized.
6. Verify messageSecret is properly set in $USER_PREFERENCES$ (see Integration guide above).