Trusted Domains Security

Trusted Domains Security

Available since version 7.6.0

The Trusted Domains feature is an optional security enhancement that allows you to restrict which URLs can be opened by the Mobile Messaging SDK. This helps protect your users from potentially malicious URLs that could be sent through push notifications.

Table of Contents

• Overview
• Configuration
• How It Works
• Domain Matching Rules
• What URLs Are Affected
• Backward Compatibility
• Examples
• Logging

Overview

When trusted domains are configured, the SDK will only open those URLs that match the specified domains. URLs from untrusted domains will be blocked and logged as warnings.

Key Benefits:

• Protection against malicious URLs
• Control over which domains your app can navigate to
• No breaking changes - completely optional feature
• Backward compatible with existing implementations

Configuration

Configure trusted domains during plugin initialization using the trustedDomains option:

MobileMessaging.init({
    applicationCode: APP_CODE,
    trustedDomains: ['example.com', 'yourdomain.com', 'api.trusted.org'],
    ...
});

Parameters:

• domains: Array of domain strings that should be trusted
• Domain format: 'example.com', 'subdomain.example.com', etc.

How It Works

The SDK validates domains for the following URL types:

• WebView URLs (webViewUrl): URLs opened in the in-app webviews
• Browser URLs (browserUrl): URLs opened in an external browser

The validation happens before opening the URL. If a URL's domain is not trusted, the SDK will:

1. Block the URL from opening
2. Log a warning message
3. Continue normal execution without the URL action

Domain Matching Rules

Exact and Subdomain Match

// Trusted domain: "example.com"
// ✅ Matches: https://example.com/page
// ✅ Matches: https://api.example.com/endpoint
// ✅ Matches: https://cdn.example.com/image.jpg
// ✅ Matches: https://www.example.com/home

Partial Match Prevention

// Trusted domain: "example.com"
// ❌ Does not match: https://badexample.com/malicious
// ❌ Does not match: https://example.com.evil.org/phishing

What URLs Are Affected

URLs That Are Validated

• HTTP/HTTPS URLs in webView actions
• HTTP/HTTPS URLs in browser actions
• URLs from push notification webViewUrl field
• URLs from push notification browserUrl field

URLs That Are NOT Validated

• Deep links (non-HTTP/HTTPS schemes like myapp://, tel:, mailto:)
• URLs handled by custom MessageHandlingDelegate implementations
• URLs opened programmatically outside of SDK notification handling

Backward Compatibility

The trusted domains feature is completely backward compatible:

• Without configuration: All URLs work exactly as before
• With empty array: trustedDomains: [] - All URLs are allowed
• With domains: Only specified domains are allowed

Examples

Configuration

MobileMessaging.init({
    applicationCode: APP_CODE,
    trustedDomains: ['example.com', 'yourdomain.com', 'api.trusted.org'],
    ...
});

URL Behavior Examples

// Configuration
trustedDomains: ['example.com', 'trusted.org']

// ✅ These URLs will be opened:
// https://example.com/page
// https://api.example.com/data
// https://www.example.com/home
// https://trusted.org/content

// ❌ These URLs will be blocked:
// https://malicious.com/phishing
// https://untrusted.net/spam
// https://fake-example.com/scam

// ✅ These deeplinks will still work (not validated):
// myapp://open-screen
// tel:+1234567890
// mailto:support@example.com
// maps://location

Logging

When URLs are blocked, the SDK logs warning messages:

URL domain is not trusted and will not be opened: https://malicious.com/phishing
Browser URL domain is not trusted and will not be opened: https://untrusted.net/spam

These logs help with debugging and monitoring security events in your application.

Related Documentation

• How to define specific action on notification or in-app primary button tap
• How to open application webView on message tap
• Mirror push notifications
• Interactive notifications