Skip to main content

Iframe Embed Integration

The iframe integration is the fastest way to add SavvyMoney credit score functionality to your platform. With minimal development effort, you can embed a fully-featured credit score experience.

Overview​

The iframe widget provides:

  • ✅ Credit score display with educational content
  • ✅ Score factors breakdown
  • ✅ Credit monitoring alerts
  • ✅ Personalized offers (optional)
  • ✅ Responsive design (mobile-friendly)
  • ✅ Automatic updates

Time to implement: 1-2 weeks

Prerequisites​

Before starting, ensure you have:

  • Partner ID from SavvyMoney
  • Sandbox credentials for testing
  • SSL-enabled website (HTTPS required)
  • User authentication system in place

Basic Implementation​

Step 1: Generate User Token​

First, generate a secure user token from your backend:

Backend: Generate User Token
// Node.js example
const response = await fetch('https://api.sandbox.savvymoney.com/v1/auth/user-token', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user-12345',
    email: '[email protected]',
    firstName: 'John',
    lastName: 'Doe'
  })
});

const { userToken } = await response.json();
Backend: Generate User Token (Java)
// Java/Spring example
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.setBearerAuth(accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);

Map<String, String> body = Map.of(
    "userId", "user-12345",
    "email", "[email protected]",
    "firstName", "John",
    "lastName", "Doe"
);

HttpEntity<Map<String, String>> request = new HttpEntity<>(body, headers);
ResponseEntity<UserTokenResponse> response = restTemplate.postForEntity(
    "https://api.sandbox.savvymoney.com/v1/auth/user-token",
    request,
    UserTokenResponse.class
);

String userToken = response.getBody().getUserToken();

Step 2: Embed the Widget​

Add the iframe to your HTML page:

Frontend: Embed Widget
<!DOCTYPE html>
<html>
<head>
  <title>Your Credit Score</title>
  <style>
    .savvymoney-container {
      width: 100%;
      max-width: 800px;
      margin: 0 auto;
    }
    .savvymoney-widget {
      width: 100%;
      height: 600px;
      border: none;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    }
  </style>
</head>
<body>
  <div class="savvymoney-container">
    <iframe
      id="savvymoney-widget"
      class="savvymoney-widget"
      src="https://widget.savvymoney.com/v2/embed?partnerId=YOUR_PARTNER_ID&token=USER_TOKEN"
      allow="fullscreen"
      title="SavvyMoney Credit Score Widget"
    ></iframe>
  </div>
</body>
</html>

Configuration Options​

URL Parameters​

Customize the widget behavior with URL parameters:

ParameterTypeRequiredDescription
partnerIdstringYesYour SavvyMoney partner ID
tokenstringYesUser-specific authentication token
themestringNolight (default) or dark
localestringNoLanguage code (e.g., en, es)
showOffersbooleanNoDisplay personalized offers
showAlertsbooleanNoDisplay credit monitoring alerts
primaryColorstringNoHex color for branding (URL encoded)

Example with Options​

<iframe
  src="https://widget.savvymoney.com/v2/embed?partnerId=YOUR_ID&token=TOKEN&theme=light&showOffers=true&primaryColor=%23004987"
  width="100%"
  height="600"
  frameborder="0"
  title="SavvyMoney Widget"
></iframe>

Responsive Design​

The widget is designed to be responsive. For optimal display across devices:

Responsive Container Styles
.savvymoney-container {
  width: 100%;
  padding: 16px;
}

.savvymoney-widget {
  width: 100%;
  min-height: 400px;
  height: calc(100vh - 200px);
  max-height: 800px;
}

/* Mobile adjustments */
@media (max-width: 768px) {
  .savvymoney-widget {
    min-height: 500px;
    height: calc(100vh - 100px);
  }
}

Event Communication​

The widget communicates with your page via postMessage:

Handling Widget Events
window.addEventListener('message', (event) => {
  // Verify origin for security
  if (event.origin !== 'https://widget.savvymoney.com') return;

  const { type, data } = event.data;

  switch (type) {
    case 'SAVVY_LOADED':
      console.log('Widget loaded successfully');
      break;

    case 'SAVVY_SCORE_VIEWED':
      console.log('User viewed their score:', data.score);
      // Track analytics event
      break;

    case 'SAVVY_OFFER_CLICKED':
      console.log('User clicked offer:', data.offerId);
      // Handle offer click
      break;

    case 'SAVVY_ERROR':
      console.error('Widget error:', data.message);
      // Handle error state
      break;

    default:
      console.log('Unknown event:', type);
  }
});

Available Events​

EventDescriptionData
SAVVY_LOADEDWidget finished loading{ timestamp }
SAVVY_SCORE_VIEWEDUser viewed their score{ score, date }
SAVVY_OFFER_CLICKEDUser clicked an offer{ offerId, offerType }
SAVVY_ALERT_VIEWEDUser viewed an alert{ alertId, alertType }
SAVVY_ERRORAn error occurred{ code, message }
SAVVY_RESIZEWidget requests size change{ height }

Security Considerations​

Content Security Policy (CSP)​

Add SavvyMoney domains to your CSP headers:

Content-Security-Policy:
  frame-src https://widget.savvymoney.com;
  connect-src https://api.savvymoney.com;

Token Security​

Important
  • Never expose your API credentials in frontend code
  • Generate user tokens server-side only
  • Tokens expire after 1 hour - refresh as needed
  • Each token is single-use; generate new tokens for each session

Testing in Sandbox​

Use these test scenarios in the sandbox environment:

Test User IDScenario
test-good-scoreUser with 750+ credit score
test-fair-scoreUser with 650-699 score
test-poor-scoreUser with below 600 score
test-thin-fileUser with limited credit history
test-frozenUser with frozen credit

Troubleshooting​

Widget Not Loading​

  1. Check browser console for errors
  2. Verify token hasn't expired
  3. Confirm CSP allows iframe from widget.savvymoney.com
  4. Test in incognito to rule out extensions

Blank White Screen​

// Add error handling
const iframe = document.getElementById('savvymoney-widget');
iframe.onerror = () => {
  console.error('Failed to load widget');
  // Show fallback UI
};

Token Errors​

If you receive token errors, verify:

  1. Token was generated within the last hour
  2. Token matches the current user session
  3. User is enrolled in SavvyMoney

Next Steps​

Last updated on