Flinks Connect & OAuth Integration (Web + Mobile)

Introduction

Flinks Connect is a pre-built UI component that enables end-users to securely connect their bank accounts via OAuth. Depending on your application, it can run in an iframe (for web) or in a WebView / browser (for mobile). This article consolidates integration guidelines, event flows, key parameters, and mobile compatibility considerations to help you build a robust OAuth experience.

1. General Guidelines & Key Parameters

Configuration

You should consult the official Flinks documentation for setup and installation details.
When initiating Flinks Connect, you will need to set parameters such as:

• redirectUrl — this must point to a domain you control (do not set this to a Flinks-owned domain) Flinks

• After a successful connection, Flinks Connect appends a loginId to the callback URL. Your application should capture and persist this loginId. Flinks

Example

If your redirect URL is e.g.

https://yourapp.com/flinks/connection/?loginId=XXXX

you should parse and record loginId for further usage. Flinks

2. Event Flow & JavaScript Integration (Web)

Flinks Connect emits standardized events you can listen to via window.postMessage (or similar) to track progress of the OAuth flow. Flinks

Example listener snippet:

<script>
  window.addEventListener('message', function(e) {
    console.log(e.data);
    // e.data might look like:
    // { step: 'APP_MOUNTED' }
    // { step: 'INSTITUTION_SELECTED', institution: 'BankX' }
    // … 
    // { step: 'REDIRECT', loginId: 'XXXXX', requestId: 'YYYY', institution: 'BankX' }
  });
</script>

A “happy path” event sequence might look like:

{step: 'APP_MOUNTED'}  
{step: 'COMPONENT_LOAD_INSTITUTION_SELECTOR', cached: false}  
{step: 'INSTITUTION_SELECTED', institution: 'FlinksCapital'}  
{step: 'COMPONENT_LOAD_CREDENTIAL', institution: 'FlinksCapital'}  
{step: 'SUBMIT_CREDENTIAL', institution: 'FlinksCapital'}  
{step: 'COMPONENT_LOAD_MFA', mfaTypes: Array(…), institution: 'FlinksCapital'}  
{step: 'SUBMIT_MFA', institution: 'FlinksCapital'}  
{step: 'REDIRECT', loginId: '***', requestId: '***', institution: 'FlinksCapital'}  
``` :contentReference[oaicite:4]{index=4}  

From the `REDIRECT` event (or via `redirectUrl` callback), you should capture the `loginId` and proceed in your backend or frontend logic.

---

## 3. Web Integration (iframe) Tips & Issues

### Responsiveness  
Your iframe container should scale properly. Example styling:

```css
.flinksconnect {
  width: 100%;
  height: 700px;
}

And use:

<iframe class="flinksconnect"
        src="https://…/v2/…">
</iframe>

to embed the Flinks Connect UI. Flinks

JavaScript / New Window Handling

If your integration needs to open new windows (e.g. for OAuth or external bank flows), you’ll need to ensure your environment allows window.open (or equivalent) from inside the iframe. Some browsers and environments may restrict this behavior. Flinks

4. WebView / Native App Integration & Challenges

Using a WebView (embedded browser inside a native mobile app) can introduce compatibility issues for OAuth flows. Cookies, cross-domain navigation, and window-opening restrictions may interfere with a smooth user experience. Flinks+1

iOS Considerations

• The default WebView setting javaScriptCanOpenWindowsAutomatically is false by default; you may need to explicitly enable it. Flinks

• Domain restrictions (e.g. navigationAppBoundDomain) may prevent navigation to external domains. Flinks

Android Considerations

• Settings like setJavaScriptCanOpenWindowsAutomatically and setJavaScriptEnabled may default to false. You must enable them to support the OAuth flow. Flinks

Hybrid / Cross-Platform (e.g. React Native WebView)

WebView configurations in hybrid frameworks may similarly default to disabling new window openings or external navigations. You’ll need to enable them explicitly. Flinks+1

5. OAuth Compatibility for Mobile Users (Best Practices)

Because of the challenges of running OAuth flows inside WebViews on mobile, Flinks recommends the following practices for mobile (iOS/Android) to ensure consistency and reduce failure rates. Flinks

1. Use the Device’s Default Browser

• Instead of embedding the OAuth flow in a WebView, launch the flow in the system’s default browser (Safari, Chrome, etc.)

• This avoids cookie mismatches and cross-domain session issues. Flinks

• To facilitate this, set the oauthWindowRedirect=true iframe (or parameter) so that the flow opens externally. Flinks

2. Always Set & Use a Redirect URL

• Pass the redirectUrl iframe parameter when initiating the OAuth flow.

• After authentication at the bank, users should be deep-linked back into your app via this redirect URL. Flinks

Why it matters: Cookie & Session Integrity

If you run the OAuth flow in a WebView, the user’s browser session (cookies) may differ from what the external bank site expects. That can lead to authentication failures, broken sessions, or inability to persist login state. Opening the flow externally ensures continuity in the same browser session. Flinks+1

6. Summary & Recommended Patterns

7. Integration Checklist

1. Configure Flinks Connect with your redirectUrl pointing to your domain.

2. Start the OAuth flow with parameters (e.g. oauthWindowRedirect) appropriate to your context.

3. For web: embed via iframe, listen for message events.

4. For mobile: redirect users to external browser session for OAuth, then deep link back.

5. Capture the loginId via REDIRECT event or from redirect URL.

6. Handle any errors, retries, or fallback flows as needed.

7. Test thoroughly across desktop browsers, iOS, Android, and hybrid environments (WebViews).