Proxy URLs

What is Proxy URL?

Proxy URLs are commonly used in extensions to enable them to send network requests on behalf of the user. Some extensions need to access resources on remote servers that may be blocked by the user's network, or they may need to access resources that are restricted by the server based on the user's location or IP address. By using a proxy server, the extension can route its network requests through a different IP address or location, bypassing any network or server restrictions.

In addition, using a proxy server can help protect the user's privacy by masking their IP address from the server. This can help prevent the user from being tracked or identified by the server based on their IP address.

Overall, using a proxy URL in extensions can provide a number of benefits, including improved network performance, enhanced security, and increased privacy for the user.

Scenario

A Proxy URL can bypass the CORS error by acting as a middleman between the browser and the API, forwarding requests to the API from the browser through the Proxy URL.
A Proxy URL can also publish or inject custom pages on a sales channel/website by intercepting storefront requests and redirecting them to custom pages or functionality, without needing direct access to the storefront API.

Architecture

QG7

Here's how this architecture works

A user initiates an HTTP request using their browser, which is then forwarded to a proxy server.
Prior to forwarding the request to the destination server, the proxy server relays the HTTP request to an extension, which responds with an HTTP request and proxy configuration.
After receiving the response from the extension, the proxy server sends both the original HTTP request and the proxy configuration to the destination server.
Upon receiving the forwarded HTTP request from the proxy server, the destination server sends an HTTP response back to the proxy server.
The proxy server then sends the received HTTP response from the destination server to the extension.
After receiving the HTTP response from the proxy server, the extension modifies it before sending it back to the proxy server.
Finally, the browser receives the modified HTTP response from the proxy server, which it then displays to the user within the browser.

Proxy URL architecture allows extensions to modify user requests and intercept responses from websites, useful for filtering content, adding features, or protecting privacy.

How to create a Proxy URL?

For creating a proxy URL, extension developers have to integrate the SDK method, in which they are required to provide the Extension API key, the attached_path , and the extension launch URL.

// Promise
const promise = client.application("<APPLICATION_ID>").partner.addProxyPath({  extensionId : value,
 body : {attached_path, proxy_url} });

// Async/Await
const data = await client.application("<APPLICATION_ID>").partner.addProxyPath({  extensionId : value,
 body : {attached_path, proxy_url} });

Let’s break down each component of this code:

client.application("<APPLICATION_ID>")

This creates an instance of the application for the given <APPLICATION_ID> that the client is authorized to access.
.partner.addProxyPath()
This is a method that is being called on the partner object of the application instance. It allows the user to add a new proxy path to their application.

extensionId : value

This specifies the extension ID that the proxy path is associated with.

body: {attached_path, proxy_url}

This is an object that contains two properties: attached_path and proxy_url. attached_path is the path on the partner server that the proxy is attached to, and proxy_url is the URL of the proxy server.

Sample Response:

{
    "_id": "607406b8a472cd527303692f",
    "attached_path": "test",
    "proxy_url": "https://www.abc.com",
    "company_id": "1",
    "application_id": "000000000000000000000004",
    "extension_id": "6073280be899ea5b1150fd9d",
    "created_at": "2021-04-12T08:37:12.077Z",
    "modified_at": "2021-04-12T08:37:12.077Z"
}

URL Format: ${application_url}/ext/${attached_path}

Example

Consider the following app proxy configuration:

attached_path: test
proxy_url
application_url
Final URL

How to remove a Proxy URL?

To remove a particular proxy of a URL extension for an application, the developer has to follow some steps.

// Promise
const promise = client.application("<APPLICATION_ID>").partner.removeProxyPath({  extensionId : value,
 attachedPath : value });

// Async/Await
const data = await client.application("<APPLICATION_ID>").partner.removeProxyPath({  extensionId : value,
 attachedPath : value });

Let’s break down each component of this code:Let’s break down each component of this code:

client.application("<APPLICATION_ID>")

This creates an instance of the application for the given <APPLICATION_ID> that the client is authorized to access.

.partner.addProxyPath()

This is a method that is being called on the partner object of the application instance. It allows the user to remove a proxy path to their application.

extensionId : value

This specifies the extension ID that the proxy path is associated with.

body: {attached_path, proxy_url}

This is an object that contains two properties: attached_path and proxy_url. attached_path is the path on the partner server that the proxy is attached to, and proxy_url is the URL of the proxy server.

Sample Response:

{
    "message": "Proxy URL deleted",
    "data": {
        "_id": "607406b8a472cd527303692f",
        "attached_path": "test",
        "proxy_url": "https://www.abc.com",
        "company_id": "1",
        "application_id": "000000000000000000000004",
        "extension_id": "6073280be899ea5b1150fd9d",
        "created_at": "2021-04-12T08:37:12.077Z",
        "modified_at": "2021-04-12T08:37:12.077Z"
     }
}

note

In the context of handling triggered events, webhooks are commonly associated with payloads.
When an extension is uninstalled, it triggers an uninstallation event and sends a message to the extension server.
This process effectively removes any attached proxy paths that are linked to the company ID for that extension.

You can subscribe to the events by passing the 'webhook_config' parameter in the setupFdk function.

let fdkExtension = setupFdk({
    api_key: config.extension.api_key,
    api_secret: config.extension.api_secret,
    base_url: config.extension.base_url,
    scopes: ["company/saleschannel", "company/application/settings"], // add your scopes
    callbacks: {
        auth: async (req) => {
            // Writee you code here to return initial launch url after suth process complete
            return `${req.extension.base_url}/company/${req.query['company_id']}`;
        },
        
        uninstall: async (req) => {
            // Write your code here to cleanup data related to extension
            // If task is time taking then process it async on other process.
        }
    },
    storage: new RedisStorage(appRedis,"exapmple-fynd-platform-extension"), // add your prefix
    access_mode: "offline",
    cluster:  config.extension.fp_api_server,// this is optional by default it points to prod.
    //debug: true
    webhook_config: {
        api_path: "/webhook",
        notification_email: "soumyaacharya@gofynd.com",
        event_map: {
            "company/extension/uninstall":{
                "handler": extensionUninstallHandler,
                "version": '1'
            }
        }
    }
});

You can refer to this link to read the payload of an extension uninstallation.

What is Proxy URL?​

Scenario​

Architecture​

Here's how this architecture works​

How to create a Proxy URL?​

Example​

How to remove a Proxy URL?​