Mobile Locker JavaScript SDK - Developer Guide

The Mobile Locker JavaScript SDK provides developers with comprehensive tools for integrating tracking, analytics, and Mobile Locker platform features into web applications and presentations.

Modern JS SDK

Legacy SDK

Do not use the legacy SDK anymore!

Installation

Install the SDK via npm:

npm install @mobilelocker/mobilelocker-tracking

Basic Usage

import mobilelocker from '@mobilelocker/mobilelocker-tracking';

// Basic event tracking
mobilelocker.logEvent('user_action', 'button_click', '/current-page', {
  buttonId: 'cta-button',
  section: 'hero'
});

CommonJS

const mobilelocker = require('@mobilelocker/mobilelocker-tracking');

// Environment detection
if (mobilelocker.isMobileLocker()) {
  console.log('Running in Mobile Locker environment');
}

Browser (UMD)

<script src="node_modules/@mobilelocker/mobilelocker-tracking/dist/index.js"></script>
<script>
  // Note: In browser, the global is still MobileLocker for compatibility
  MobileLocker.logEvent('page', 'view', window.location.pathname);
</script>

TypeScript Support

The SDK includes full TypeScript support with IntelliSense and auto-completion:

import mobilelocker from '@mobilelocker/mobilelocker-tracking';

// TypeScript will provide full type checking and auto-completion
mobilelocker.setDebugMode(true);
const logs: any[] = mobilelocker.getDebugLogs();

Core Features

1. Environment Detection

Detect the runtime environment to conditionally execute code:

// Check if running in any Mobile Locker environment
if (mobilelocker.isMobileLocker()) {
  // Code specific to Mobile Locker
}

// Check if running in the native iOS/desktop app
if (mobilelocker.isMobileLockerApp()) {
  // App-specific functionality
}

// Check if running in the browser version
if (mobilelocker.isMobileLockerCDN()) {
  // Browser-specific functionality
}

2. Event Tracking & Analytics

Track user interactions and custom events:

// Basic event tracking
mobilelocker.logEvent('category', 'action', '/page-path', {
  customData: 'value'
});

// Session modes for reporting
mobilelocker.liveMode('/current-page');     // Count events in reports
mobilelocker.practiceMode('/current-page'); // Exclude from reports

3. Form Handling & Data Capture

Submit form data to the Mobile Locker system:

// Submit form data
const formData = {
  name: 'John Doe',
  email: 'john@example.com',
  company: 'Acme Corp'
};

mobilelocker.submitForm('contact-form', formData)
  .then(() => console.log('Form submitted successfully'))
  .catch(error => console.error('Form submission failed:', error));

// Alternative method name
mobilelocker.captureData('lead-form', formData);

4. User Storage (Persistent Data)

Save and retrieve user data across sessions:

// Save user data
const userData = { preferences: { theme: 'dark' }, progress: 75 };
mobilelocker.saveUserStorage('user-preferences', userData)
  .then(() => console.log('Data saved'))
  .catch(error => console.error('Save failed:', error));

// Fetch user data for current user
mobilelocker.fetchUserStorageForCurrentUser()
  .then(data => console.log('User storage:', data));

// Fetch user data for specific presentation
mobilelocker.fetchUserStorageForPresentation(123)
  .then(data => console.log('Presentation storage:', data));

// Delete user data
mobilelocker.deleteUserStorage('user-preferences')
  .then(() => console.log('Data deleted'));

5. Email & Communication

Send emails and share presentations:

// Send email
mobilelocker.sendEmail(
  'recipient@example.com',           // To
  'Subject Line',                    // Subject
  '<h1>HTML Email Body</h1>',       // Body (HTML)
  'attachments/file.pdf',           // Attachment (optional)
  'templates/email.html',           // Template (optional)
  { customData: 'value' }           // Additional data (optional)
);

// Share presentation
const recipients = [
  { email: 'user1@example.com', name: 'User One' },
  { email: 'user2@example.com', name: 'User Two' }
];

mobilelocker.sharePresentation(
  recipients,
  mobilelocker.notificationLevels.NOTIFY_EVERY, // Notification level
  true // Send reminders
);

6. CRM Integration

Access CRM data (requires appropriate permissions):

// Get CRM accounts
mobilelocker.getAccounts()
  .then(accounts => console.log('Accounts:', accounts));

// Get contacts
mobilelocker.getContacts()
  .then(contacts => console.log('Contacts:', contacts));

// Get user contacts with pagination
mobilelocker.getChunkedUserContacts(0, 100)
  .then(contacts => console.log('User contacts:', contacts));

// Get CRM users (requires iOS app 3.18.8+)
mobilelocker.getCRMUsers()
  .then(users => console.log('CRM users:', users));

7. Presentation Management

Control presentation behavior:

// Get current presentation info
mobilelocker.getPresentation()
  .then(presentation => console.log('Current presentation:', presentation));

// Get all accessible presentations
mobilelocker.getPresentations()
  .then(presentations => console.log('Available presentations:', presentations));

// Open presentation by ID or name
mobilelocker.openPresentationByID(123);
mobilelocker.openPresentationByName('Demo Presentation');

// Show presentation picker
mobilelocker.openPresentationPicker();

// Reload current presentation
mobilelocker.reloadPresentation();

Debug Mode (Essential for Development)

The SDK includes a comprehensive debug mode system, especially useful when testing in the iOS app where console access is limited:

Enable Debug Mode

// Enable debug mode
mobilelocker.setDebugMode(true);

// Check if debug mode is active
console.log('Debug mode:', mobilelocker.isDebugMode());

Retrieve Debug Logs Programmatically

Perfect for iOS app debugging where console.log isn't accessible:

// Get all debug logs
const allLogs = mobilelocker.getDebugLogs();
console.log('Total debug entries:', allLogs.length);

// Filter logs by category
const requestLogs = mobilelocker.getDebugLogsFiltered({ 
  category: 'request' 
});

// Filter logs by level
const errorLogs = mobilelocker.getDebugLogsFiltered({ 
  level: 'error' 
});

// Filter logs by time
const recentLogs = mobilelocker.getDebugLogsFiltered({ 
  since: new Date(Date.now() - 60000) // Last minute
});

// Clear debug logs
mobilelocker.clearDebugLogs();

Debug Categories

  • request  - HTTP request details
  • response  - HTTP response details
  • event  - Event tracking and analytics
  • error  - Error context and debugging
  • general  - General SDK operations

Error Handling

The SDK provides structured error handling with detailed error information:

try {
  await mobilelocker.submitForm('contact-form', formData);
} catch (error) {
  if (error instanceof mobilelocker.MobileLockerError) {
    console.error('SDK Error:', error.code, error.message);
    console.error('Response:', error.response);
    console.error('Original error:', error.originalError);
    
    // Get JSON representation
    console.error('Error details:', error.toJSON());
  }
}

Notification Levels

Use these constants for presentation sharing:

mobilelocker.notificationLevels.NOTIFY_NONE     // 0 - Never notify
mobilelocker.notificationLevels.NOTIFY_FIRST    // 1 - First click only
mobilelocker.notificationLevels.NOTIFY_EVERY    // 2 - Every click
mobilelocker.notificationLevels.NOTIFY_WEEKLY   // 3 - Weekly summary
mobilelocker.notificationLevels.NOTIFY_MONTHLY  // 4 - Monthly summary

Browser Compatibility

  • Modern Browsers: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
  • Node.js: Version 16.0.0 or higher
  • Mobile Locker iOS App: All versions
  • Mobile Locker Desktop App: All versions

Common Use Cases

1. Track Page Views

// Track page navigation
mobilelocker.logEvent('navigation', 'page_view', window.location.pathname);

2. Form Submission with Validation

function submitContactForm(formData) {
  // Validate data first
  if (!formData.email || !formData.name) {
    throw new Error('Required fields missing');
  }
  
  return mobilelocker.submitForm('contact-form', formData);
}

3. Conditional Feature Loading

if (mobilelocker.isMobileLockerApp()) {
  // Load native app features
  loadNativeFeatures();
} else if (mobilelocker.isMobileLockerCDN()) {
  // Load browser-specific features
  loadBrowserFeatures();
} else {
  // Load fallback features
  loadFallbackFeatures();
}

4. Debug Mode Setup for Testing

// Enable debug mode for development
if (process.env.NODE_ENV === 'development') {
  mobilelocker.setDebugMode(true);
  
  // Log environment info
  console.log('SDK Environment:', {
    isMobileLocker: mobilelocker.isMobileLocker(),
    isMobileLockerApp: mobilelocker.isMobileLockerApp(),
    isMobileLockerCDN: mobilelocker.isMobileLockerCDN()
  });
}

5. Error Monitoring

// Set up global error handler for SDK errors
window.addEventListener('unhandledrejection', (event) => {
  if (event.reason instanceof mobilelocker.MobileLockerError) {
    // Send to your error monitoring service
    console.error('Mobile Locker SDK Error:', event.reason.toJSON());
    
    // Get debug logs for context
    const debugLogs = mobilelocker.getDebugLogs();
    console.log('Debug context:', debugLogs.slice(-5)); // Last 5 entries
  }
});

Troubleshooting

Debug Mode Not Working

  1. Ensure debug mode is enabled: mobilelocker.setDebugMode(true)  
  2. Check debug logs: mobilelocker.getDebugLogs().length  
  3. Verify environment detection is working

Form Submission Issues

  1. Enable debug mode and check request logs
  2. Verify you're in a Mobile Locker environment
  3. Check for validation errors in the response

CRM Data Access Issues

  1. Verify you're running in the Mobile Locker app
  2. Check user permissions for CRM access
  3. Ensure minimum iOS app version requirements are met

Network/API Issues

  1. Check debug logs for request/response details
  2. Verify JWT token is present and valid
  3. Check Mobile Locker environment detection

Support

For technical support and questions about the Mobile Locker SDK:

Email: support@mobilelocker.com

Documentation: https://help.mobilelocker.com/article/371-mobile-locker-javascript-sdk-developer-guide

When contacting support, please include:

  • SDK version (npm list @mobilelocker/mobilelocker-tracking  )
  • Environment (iOS app, browser, Node.js)
  • Debug logs if applicable (mobilelocker.getDebugLogs()  )
  • Code samples demonstrating the issue
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us

Related Articles