Widget Domain Proxy (Legacy)

CrowdTwist natively supports multiple widget domains for a single CrowdTwist instance. For more information please contact your Oracle CrowdTwist representative or Oracle Support.

Overview

The Oracle CrowdTwist platform allows clients to embed our loyalty solution directly into their existing sites through the use of widgets and the widget SDK. As a part of our offering, we support a first-party experience through the use of a delegated subdomain. With this, widget elements on the page appear first party to the end user’s browser for a seamless experience.

Recently, web browsers have been moving to limit third party content/cookies to address security and privacy concerns for their users. Accordingly, CrowdTwist has recommended that all clients utilize first party cookies to ensure a seamless loyalty experience by preventing browsers from inadvertanly blocking CrowdTwist-powered loyalty elements. Each CrowdTwist instance/program can be configured with a single domain.

That said, if a program exists across more than one domain, additional steps will need to be included in the implementation process in order to support a first party loyalty experience. Below is the recommended approach.

Implementation

Proxy

The implementation approach essentially includes a proxy server that is set up on the various brand domains through the proxy’s own subdomain (i.e. loyalty.brand.com). This proxy mimics the normal operation of widgets on the front-end, but end user requests are made to the proxy first and then subsequently forwarded to the CrowdTwist platform provide the relevant loyalty content requested. The proxy then takes the response from CrowdTwist and forwards it back to the front end in the relevant first party brand-level domain.

The relevant program brand-level domains included in this process will need their own SSL certificates, in addition to the domain in which the proxy uses, as the connections will still utilize SSL (specifically TLS v1.2 protocol). For example, an SSL certificate will need to be acquired and maintained for the main program domain the proxy uses (CrowdTwist program domain) as well as the revelant brand domains such as ct-prod.brandA.com, ct-prod.brandB.com, ct-prod.brandC.com, etc. in order to provide the loyalty experience on each individual brand level site.

Note, no changes are needed to the CrowdTwist Widget SDK on the site for the proxy to work. The widgets and the SDK are built to support first party domains even when the SDK is in the CrowdTwist domain.

Cookie Translation

A part of this process requires the standard CrowdTwist authentication API to be carried out by the proxy and the resulting cookies “translated” to the relevant brand domain. After receiving the CrowdTwist domain cookies from the User Authentication API procedure, cookies in the main program domain need to be rewritten via the proxy to the specific brand domain that the end user is requesting data from in order to be accepted as first-party. Note the cookie name and values need to be maintained explicitly in order for the cookie to be recognized by CrowdTwist in future proxied requests. Once completed, the domain of the cookies will match that of the widget content via the proxy.

Content Substitution

After the cookies have been appropriately set in the first party domain, the proxy will need to take any incoming requests from the browser to the proxy and forward them on to CrowdTwist ensuring that the cookie names, cookie values, request headers, and request details are unchanged. There are a few requests that can be made by the widgets beyond the initial request for widget content, we have detailed these below:

  • Widget Request – https://ct-prod.brand.com/request?widgetId=XXXX

    • The widgetId value should be obtained from the browser request and included within the subsequent proxy request to CrowdTwist.

  • Redemption post to carry out reward redemption – https://ct-prod.brand.com/reward/rpc

  • Survey post to submit survey responses – https://ct-prod.brand.com/questionnaire/rpc

  • Receipt Scan Post – https://ct-prod.brand.com/user/rpc

  • Loyalty user detail – https://ct-prod.brand.com/request

  • Restricted Files - https://ct-prod.brand.com/restrictedfile

Other Considerations

Specifically for iOS devices there is an additional consideration for the proxy beyond the above. Due to how Apple handles modals on iOS devices, CrowdTwist uses new tabs (rather than modals) for actions such as reward redemption. The user is redirected via a JavaScript generated page utilizing the CrowdTwist configured program domain. These interactions will need to be accounted for and updated to follow the new proxied URL scheme in order to function correctly.