Toolset Integration

The WellcomeMat Embedded Toolset allows partners to seamlessly integrate WellcomeMat’s media management capabilities directly into their own websites. With this toolset, you can enable features such as:

• Video Uploads
• Video Unbrander
• Video Chaptering
• Preview Page
• Media History
• Social Distribution
• Analytics Reporting

The embedded toolset can be integrated using either a popup window or an embedded iframe, providing flexibility depending on your website’s design and user experience requirements.

Toolset URL

To test the embedded toolset, use the following base URL:

https://www.wellcomemat.com/embed/uploader?key=<KEY>&secret=<SECRET>

Replace <KEY> and <SECRET> with your assigned API credentials, or use another Authentication method below:

Authentication Params

A valid combination of authentication parameters need to be included in the URL params for the request to succeed. For a given authentication option all parameters are required.

Option 1: secret

Option 2: auth_hash

Option 3: token

For a more secure and flexible integration, partners can use a JWT token for authentication. The token can be generated in two ways:

1. Signed by the Partner
   • If WellcomeMat has one or more public keys registered for the partner’s account, the partner can generate a JWT token signed with their corresponding private key.
2. Signed by WellcomeMat
   • The partner can call WellcomeMat’s API to request a JWT token. This token will be generated and signed by the WellcomeMat system using the partner’s key and secret.

The token can be scoped to a specific sub-user by embedding relevant claims within the signed JWT (such as unique_id). When WellcomeMat processes the token, it validates these claims and ensures that the actions performed through the Toolset are restricted to the specified sub-user. This approach allows partners to securely delegate access and control to individual users while maintaining overall account-level management. Additionally, by including an expiration claim (exp), partners can further limit the token’s validity period, thereby enhancing security.

The inner contents of token can also include other URL parameters, which can be either authoritative (signed) or non-authoritative (unsigned). This distinction allows partners to maintain flexibility in using URL parameters while ensuring critical data integrity.

Option 4: sso

WellcomeMat can work with partner SSO (Single Sign-On) providers to require your end-users to have active sessions within your existing console. This approach is ideal when your users are already mapped to your provider via email or another identifier within the listing data (e.g., Member ID, Agent ID, Broker ID, etc.)

To facilitate seamless authentication, WellcomeMat expects the partner’s SSO provider to issue a valid session token or assertion upon successful login. The token or session data is then used to verify the user’s identity when accessing the Toolset.

General Params

The following query parameters can be passed in the toolset URL to control its behavior:

Upload Params

The following *optional* parameters can be passed to the uploader component of the Toolset. If the media already exists, these parameters will be ignored. For MLS integrations many of these values may be overwritten during Listing data syncs. See Media Upload

Important Notes

1. Social Distribution Support
   To enable social distribution features, contact WellcomeMat support to ensure your account has the necessary permissions.

2. Using Callbacks
   If you need to receive the media object after an upload completes, use the callback_location parameter in the URL. Other callback parameters are not supported for this feature.

3. Metadata and SEO
   Providing high-quality metadata with your videos improves your ability to query content, enhances SEO, and optimizes display on social media platforms.

4. MLS Integration
   For MLS partners, WellcomeMat offers automatic video property and cover photo imports using data sources such as RESO and RETS.

Common Scenarios

Popout vs. iframe

• If iframe element in an existing page, use logo=0 to avoid excessive branding
• If iframe, consider capturing javascript events (below) so your UI can be responsive.
• If iframe and using sso, your SSO provider will likely need to whitelist wellcomemat.com on their security settings.

Broker Integrators

• Include appropriate default_state and video_type values.
• Include listing-related data parameter values in the URL (title, description, keywords, address, postal_code, price, bedrooms, bathrooms, etc.)
• Include unique_id (or broker_id) value to link to an existing sub-account as the new media owner.

MLS Integrators

• Include the Listing ID as the customid value.
• Include the Member ID (often the Agent ID or Broker ID) as the unique_id value.

1. HAVE provided a way for WellcomeMat to sync MLS data:
   • If default_photo is not provided, we will attempt to set it using the default listing photo.
2. Have NOT provided a way for WellcomeMat to sync MLS data:
   • Include the appropriate video_type value.
   • Include the listing-related data parameter values in the URL.
   • Include default_photo URL for a cover photo to match a listing.

Embedding the Toolset via an iFrame

We recommend embedding the toolset using an iframe with the following dimensions:

• Minimum size without social distribution:
  Width: 430px | Height: 650px

• Minimum size with social distribution enabled:
  Width: 1200px | Height: 800px

Here’s an example iframe embed code:

<iframe
  src="https://www.wellcomemat.com/embed/uploader?key=<KEY>&secret=<SECRET>"
  id="toolset_frame"
  width="1200"
  height="800"
  referrerpolicy="unsafe-url"
  frameborder="0"
  scrolling="no"
  allowfullscreen
  allow="clipboard-write"
  style="margin-left:auto; margin-right:auto; display:block;"
>
</iframe>

Making the iFrame Responsive

You can acheive a fully responsive iframe by setting its width and height using CSS. This example sets the iframe width to 85% of the viewport width, with an adjustable height.

<style>
  .responsive-iframe {
    width: 85vw; /* 85% of the viewport width */
    height: 75vh; /* 75% of the viewport height */
    max-width: 1200px; /* Optional max width */
    max-height: 800px; /* Optional max height */
    border: 0;
    margin-left: auto;
    margin-right: auto;
    display: block;
  }
</style>
 
<iframe
  src="https://www.wellcomemat.com/embed/uploader?key=<KEY>&secret=<SECRET>"
  class="responsive-iframe"
  allowfullscreen
  allow="clipboard-write"
  referrerpolicy="unsafe-url"
  scrolling="no"
>
</iframe>

Capturing Events via iFrame Listener

The embedded toolset iframe sends specific MessageEvent listener events that allow you to capture key user interactions, such as uploads and deletions.

Supported Events

• Upload Event: Triggered when a new media upload completes successfully.
  Payload is the Media response.
• Delete Event: Triggered when a media item is deleted.
  Payload is the MediaDeactivateResponse.

Example Listener Code

Here is sample JavaScript to listen for both upload and delete event messages:

// Listen for Upload and Delete events
window.addEventListener("message", (event) => {
  try {
    const eventType = event.data.type || "";
 
    if (eventType === "upload") {
      // Outputs `Media` response
      console.log("Media Uploaded:", event.data.payload);
    } else if (eventType === "delete") {
      // Outputs `MediaDeactivate` response
      console.log("Media Deleted:", event.data.payload);
    }
  } catch (error) {
    console.error("Error handling message event:", error);
  }
});

The same code in TypeScript:

type MediaEventPayload =
  | { type: "upload"; payload: Media }
  | { type: "delete"; payload: MediaDeactivateResponse };
 
/**
 * Type definitions can be found:
 * https://docs.wellcomemat.com/api-specs/media
 * https://docs.wellcomemat.com/api-specs/media/deactivate
 */
 
// Listen for Upload and Delete events
window.addEventListener("message", (event: MessageEvent<MediaEventPayload>) => {
  try {
    if (event.data && typeof event.data.type === "string") {
      const eventType = event.data.type;
 
      if (eventType === "upload") {
        console.log("Media Uploaded:", event.data.payload);
      } else if (eventType === "delete") {
        console.log("Media Deleted:", event.data.payload);
      }
    } else {
      console.warn("Unexpected event data format:", event.data);
    }
  } catch (error) {
    console.error("Error handling message event:", error);
  }
});