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 enabledfilter
(Object): Query parameters to retrieve the record. Field(s) used in the filter must be indexed.expiry
(Number): JWT token expiration time in secondsshardKey
(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 fieldsparams
(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 recordeventParams
(Object): Event parameters, as shown below:app_code
(String): Use to define how you'd like to group related eventsevent_code
(String): Use to define the type of eventevent_path
(String): Use to further categorize the eventevent_element
(String): Use to further categorize the eventevent_date
(String): Date of the eventevent_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 recordnewRecordParams
(Object): New record parameters, as defined below:event_path
(String): Use to further categorize the eventevent_element
(String): Use to further categorize the eventevent_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 recordreferredPurl
: 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