Skip to main content

Configuration

Complete reference for all widget configuration options.

Required Options​

OptionTypeDescription
targetstringCSS selector for the container element
apiEndpointstringYour backend proxy endpoint URL
serverIdnumberVanityCert server ID where certificates will be installed
userIdstringUnique identifier for the current user (for state persistence)

Example​

VanityCert.init({
  target: '#ssl-widget',
  apiEndpoint: '/api/vanitycert-proxy',
  serverId: 123,
  userId: 'user-abc123'
});

Optional Options​

OptionTypeDefaultDescription
themeobject{}Custom theme colors (see Theming)
callbacksobject{}Event callbacks (see Callbacks)
pollIntervalnumber5000Status polling interval in milliseconds (certificate issuance)
dnsPollIntervalnumber10000DNS validation polling interval in milliseconds

Example with All Options​

VanityCert.init({
  // Required
  target: '#ssl-widget',
  apiEndpoint: '/api/vanitycert-proxy',
  serverId: 123,
  userId: currentUser.id,

  // Optional: Theming
  theme: {
    primaryColor: '#10243f',
    secondaryColor: '#1867a0',
    successColor: '#28a745',
    fontFamily: '"Helvetica Neue", Arial, sans-serif'
  },

  // Optional: Polling
  pollInterval: 3000,      // Check certificate status every 3s
  dnsPollInterval: 15000,  // Check DNS every 15s

  // Optional: Callbacks
  callbacks: {
    onDomainCreated: function(domain) {
      console.log('Domain created:', domain);
    },
    onDnsValidated: function(domain) {
      console.log('DNS validated:', domain);
    },
    onCertificateIssued: function(domain) {
      console.log('Certificate issued:', domain);
    },
    onValidationFailed: function(domain, reason) {
      console.error('Validation failed:', reason);
    },
    onError: function(error) {
      console.error('Error:', error);
    },
    onComplete: function(domain) {
      console.log('Setup complete:', domain);
    }
  }
});

Callbacks​

The widget provides callbacks for all major events in the certificate provisioning lifecycle.

onDomainCreated​

Called when a domain is successfully created in VanityCert.

callbacks: {
  onDomainCreated: function(domain) {
    // domain = { id, url, dns_status, ssl_status, created_at }
    console.log('Domain created:', domain.url);

    // Example: Track in analytics
    analytics.track('SSL Setup Started', {
      domain: domain.url,
      domain_id: domain.id
    });
  }
}

Parameters:

  • domain (object) - Domain object with id, url, dns_status, ssl_status, created_at

onDnsValidated​

Called when DNS validation succeeds.

callbacks: {
  onDnsValidated: function(domain) {
    console.log('DNS validated for:', domain.url);

    // Example: Show notification
    showNotification('DNS configured correctly!', 'success');
  }
}

Parameters:

  • domain (object) - Updated domain object

onCertificateIssued​

Called when the SSL certificate is issued and active.

callbacks: {
  onCertificateIssued: function(domain) {
    console.log('Certificate issued for:', domain.url);

    // Example: Update UI
    document.getElementById('ssl-status').textContent = 'Active';

    // Example: Send notification email
    fetch('/api/notify-user', {
      method: 'POST',
      body: JSON.stringify({
        userId: currentUser.id,
        message: `SSL certificate ready for ${domain.url}`
      })
    });
  }
}

Parameters:

  • domain (object) - Domain with ssl_status: 'active'

onValidationFailed​

Called when DNS validation fails after 24 hours.

Important: Use this callback to email your users about DNS configuration issues.

callbacks: {
  onValidationFailed: function(domain, reason) {
    console.error('Validation failed:', reason);

    // Example: Send email to user
    fetch('/api/send-dns-failure-email', {
      method: 'POST',
      body: JSON.stringify({
        userId: currentUser.id,
        domain: domain.url,
        reason: reason
      })
    });

    // Example: Create support ticket
    createSupportTicket({
      user: currentUser,
      subject: `DNS validation failed for ${domain.url}`,
      description: reason
    });
  }
}

Parameters:

  • domain (object) - Failed domain object
  • reason (string) - Failure reason (e.g., "DNS validation timeout (24 hours)")

onError​

Called when any error occurs (network issues, API errors, etc).

callbacks: {
  onError: function(error) {
    // error = { code, message, details }
    console.error('Widget error:', error.message);

    // Example: Log to error tracking service
    Sentry.captureException(new Error(error.message), {
      extra: {
        code: error.code,
        details: error.details
      }
    });

    // Example: Show user-friendly message
    showNotification('Something went wrong. Please try again.', 'error');
  }
}

Parameters:

  • error (object) - Error object with code, message, details

onComplete​

Called when the user clicks "Done" on the final success screen.

callbacks: {
  onComplete: function(domain) {
    console.log('Setup complete:', domain);

    // Example: Redirect to dashboard
    window.location.href = '/dashboard';

    // Example: Close modal
    closeModal();

    // Example: Refresh data
    refreshDomainList();
  }
}

Parameters:

  • domain (object) - Completed domain object

API Methods​

VanityCert.init(config)​

Initialize a new widget instance.

const widget = VanityCert.init({
  target: '#ssl-widget',
  apiEndpoint: '/api/proxy',
  serverId: 123,
  userId: 'user-123'
});

Returns: VanityCertWidget instance

VanityCert.getInstance(target)​

Get an existing widget instance.

const widget = VanityCert.getInstance('#ssl-widget');

if (widget) {
  console.log('Widget exists');
}

Returns: VanityCertWidget instance or null

VanityCert.destroy(target)​

Destroy a widget instance and clean up.

VanityCert.destroy('#ssl-widget');

Widget Instance Methods​

Once you have a widget instance, you can call these methods:

widget.handleRetry()​

Retry domain setup after validation failure.

const widget = VanityCert.getInstance('#ssl-widget');
widget.handleRetry();

widget.handleCancel()​

Cancel domain setup and reset widget.

const widget = VanityCert.getInstance('#ssl-widget');
widget.handleCancel();

widget.handleDone()​

Complete the setup process (called automatically on success screen).

const widget = VanityCert.getInstance('#ssl-widget');
widget.handleDone();

State Management​

The widget automatically persists state to LocalStorage using the key vanitycert_${userId}.

Stored State​

{
  step: 2,
  domainId: 456,
  domainUrl: 'app.example.com',
  dnsStatus: 'pending',
  sslStatus: 'pending',
  createdAt: '2025-01-01T12:00:00Z'
}

State Lifecycle​

State is saved when:

  • Domain is created
  • Status is updated
  • User navigates between steps

State is cleared when:

  • User clicks "Done" on success screen
  • User clicks "Cancel" during setup
  • widget.handleDone() or widget.handleCancel() is called

Manual State Management​

// Get current state
const widget = VanityCert.getInstance('#ssl-widget');
const state = widget.state;

// Clear state manually
widget.clearState();

// Load state
widget.loadState();

Complete Configuration Example​

VanityCert.init({
  // Required
  target: '#ssl-widget',
  apiEndpoint: '/api/vanitycert-proxy',
  serverId: 123,
  userId: 'user-' + currentUser.id,

  // Theming
  theme: {
    primaryColor: '#10243f',
    secondaryColor: '#1867a0',
    tertiaryColor: '#92c2e9',
    successColor: '#28a745',
    errorColor: '#dc3545',
    fontFamily: '"Helvetica Neue", Arial, sans-serif',
    fontSize: '16px',
    borderRadius: '8px'
  },

  // Polling intervals
  pollInterval: 5000,
  dnsPollInterval: 10000,

  // Callbacks
  callbacks: {
    onDomainCreated: (domain) => {
      analytics.track('SSL_Setup_Started', { domain: domain.url });
    },

    onDnsValidated: (domain) => {
      analytics.track('DNS_Validated', { domain: domain.url });
    },

    onCertificateIssued: (domain) => {
      analytics.track('Certificate_Issued', { domain: domain.url });
      showNotification('Your SSL certificate is ready!', 'success');
    },

    onValidationFailed: (domain, reason) => {
      fetch('/api/notify-dns-issue', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          userId: currentUser.id,
          domain: domain.url,
          reason: reason
        })
      });
    },

    onError: (error) => {
      Sentry.captureException(new Error(error.message));
      showNotification('An error occurred. Please try again.', 'error');
    },

    onComplete: (domain) => {
      window.location.href = '/dashboard?ssl=success';
    }
  }
});

Next Steps​