MindFire's Javascript SDK (Pixel)

This Javascript Software Development Kit (JS SDK), also called the MindFire "Pixel", is a code snippet placed on a third-party website to interact with the MindFire Services from the browser.

WARNING

Before using the JS SDK, you need to configure the "Remote Access" to allow your domain to access your account. Learn how to set it up here.

STEP 1: Loading the JS SDK

Once you have configured the "Remote Access" to allow your domain to access your account (using the PURL field to authenticate), you can load the JS SDK on your page.

Include the following code on your page, before the closing </head> tag.

<!-- MindFire Services JS SDK -->
<script>
    window._mfaid = "<MINDFIRE_ACCOUNT_ID>";
    window._mfpurl = "<RECORD_PURL>";
</script>
<script src="https://mf-cdn.web.app/pixel-v020.js"></script>

Replace <MINDFIRE_ACCOUNT_ID> with your MindFire Account ID.

Replace <RECORD_PURL> with the value of PURL for the record you want to access on the browser.

TIP

If you are using the SDK on a landing page hosted on your MindFire's Microsite, you can use the variable ##purl## on that page to dynamically pass the records's PURL value.

<script>
    window._mfaid = "<MINDFIRE_ACCOUNT_ID>";
    window._mfpurl = "##purl##";
</script>
<script src="https://mf-cdn.web.app/pixel-v020.js"></script>

WARNING

Notice that the JS SDK file name ends with a version identifier, such as (pixel-v020). It's recommended to always use the latest version. Refer to our changelog for the most recent updates and instructions.

STEP 2: Using the JS SDK

Once you have included the SDK, you can access the _MFS object to interact with MindFire Services.

Here's an example. The following snippet is added before the closing </body> tag on a PURL page that has JS SDK loaded and initialized with the MindFire Account ID, and the PURL of a record.

<script>
(async ()=> {
      try {
        // get the record from the MindFire database.
        const record = await _MFS.getRecord(); 
        
        // Update city and state values of this record.
        await record.update({
          city: "Irvine", 
          state: "CA"
        });

        // Add a new event to this record's events.
        await record.addEvent({
          app_code: "800",
          event_code: "80101",
          event_path: "QR Code",
          event_element: "Direct Mail",
          event_date: new Date().toISOString()
        });
      } catch(e) {
        console.log(e);
      }      
    })();
</script>

Note that a try... catch statement is wrapped in an Immediately Invoked Function Experession (IIFE).

Using a try...catch statement allows you to catch any errors and handle them properly. Here we're only logging the error to the console, but in a real-life use case, you'd want to notify the user that something is not working as expected. To learn more about try...catch statement, read: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch

Using an IIFE prevents potential glabal name collisions by creating a scope for your code, and allows for execution of async functions. To learn more about IIFE, read: https://developer.mozilla.org/en-US/docs/Glossary/IIFE

API Reference

getAuthenticatedRecord(aid, filter, expiry, shardKey)

Authenticates and retrieves a record with additional utility functions.

Parameters

• aid (String): MindFire Account ID with Remote Access enabled
• filter (Object): Query parameters to retrieve the record. Field(s) used in the filter must be indexed.
• expiry (Number): JWT token expiration time in seconds
• shardKey (String): PURL value of the record used as the shardKey

Returns

Promise resolving to a record object with the following methods:

• update(params): Updates the record's data fields

  • params (Object): A JSON object containing the fields to update and their new values.
  • Returns: Promise resolving to record

• addEvent(eventParams): Adds an event to the record

  • eventParams (Object): Event parameters, as shown below:
    • app_code (String): Use to define how you'd like to group related events
    • event_code (String): Use to define the type of event
    • event_path (String): Use to further categorize the event
    • event_element (String): Use to further categorize the event
    • event_date (String): Date of the event
    • event_data (Object): A JSON object containing the custom data to be added to the event
  • Returns: Promise resolving to record

• addNewRecord(newRecordParams): Adds a new record created by the authenticated record

  • newRecordParams (Object): New record parameters, as defined below:
    • event_path (String): Use to further categorize the event
    • event_element (String): Use to further categorize the event
    • event_date (String): Date of the event (defaults to current date if not provided)
    • event_data (Object): A JSON object used to create the new record. Must include the PURL generation and deduplication fields for this account:
      • <purl_generation_field> (String): The field(s) used to generate the PURL for the new record (required)
      • <deduplication_field> (String): The field(s) used to deduplicate the new record (required)
      • no_duplicate (Boolean): Whether to prevent adding duplicate records (optional, defaults to false)
  • Returns: Promise resolving to record, or an error with 400 status code if the PURL generation or deduplication fields are not provided, or if a record already exists and the no_duplicate flag is set to true.

INFO

When using addNewRecord(), the newly created record will have two special properties:

• referredBy: The _id of the authenticated record that added the new record
• referredPurl: The PURL of the authenticated record that added the new record

This feature uses a special event code (99999) and is useful for tracking referral programs.

Examples

// Get the authenticated record
const record = await _MFS.getAuthenticatedRecord(
    "1234567890", // MindFire Account ID
    { email: "test@test.com" }, // email field should be indexed in this MindFire account
    30, // JWT token expiration time in seconds
    "johnsmith" // PURL value of the record used as the shardKey
);

// Update record's data fields
await record.update({
  city: "New York",
  state: "NY",
  zip: "10001",
  country: "United States",
  phone: "1234567890",
  email: "test@test.com"
});

// Add an event to the record, with custom data in the event_data field
await record.addEvent({
  app_code: "promos",
  event_code: "70561",
  event_path: "Direct Mail",
  event_element: "New Year Promo",
  event_date: new Date().toISOString(),
  event_data: { 
    favorite_color: "Blue",
    shirt_size: "L",
    contact_method: "text",
    points: 10 // Note this field is passed as a number, not a string
  }
});

// Add a new record created by the authenticated record
await record.addNewRecord({
  event_path: "Referral",
  event_element: "Partners",
  event_data: { // data used to create the new record
    firstname: "Sarah", // PURL generation field (required)
    lastname: "Doe", // PURL generation field (required)
    email: "sarahdoe@example.com", // Deduplication field (required)
    phone: "1234567890", // phone number of the new record
    no_duplicate: true, // if a record already exists, a new one will not be created
  }
});

getRecordPublicData(aid, purl)

Retrieves the public data for a record as defined by the account's Remote Access configurations.

Parameters

• aid (String): MindFire Account ID (defaults to window._mfaid)
• purl (String): Record's PURL (defaults to window._mfpurl)

Returns

Promise resolving to record's public data

Examples

// get the public data for a record with the PURL "marysmith" in the MindFire account with the Account ID "12345"
const record = await _MFS.getRecordPublicData("12345", "marysmith");

// get the public data for the record on the current PURL page
const record = await _MFS.getRecordPublicData();

getRecord(aid, filter, expiry, shardKey)

Convenience wrapper around getAuthenticatedRecord with default parameters.

Parameters

• aid (String): MindFire Account ID (defaults to window._mfaid)
• filter (Object): Query parameters (defaults to {purl: window._mfpurl})
• expiry (Number): JWT expiration in seconds (defaults to 60)
• shardKey (String): PURL value used as shardKey (defaults to window._mfpurl)

Returns

Same as getAuthenticatedRecord

Examples

// Using defaults
const record = await _MFS.getRecord();

// With custom parameters
const record = await _MFS.getRecord(
    "670",
    { email: "user@example.com" },
    30,
    "janecollins"
);

Error Handling

All API methods throw errors for:

• Network failures
• Invalid responses (non-200 status codes)
• JSON parsing errors

Errors should be caught using try/catch blocks:

try {
    const record = await _MFS.getRecord();
} catch (error) {
    console.error("Failed to retrieve record:", error);
}

Security Considerations

• Ensure your Account ID has appropriate Remote Access permissions
• JWT tokens expire based on the provided expiry parameter, defaults to 60 seconds
• Only public data is accessible through getRecordPublicData