In-App Installation Guide

Part 1: Administrative Setup

A. Secret Token Configuration

Navigate to Admin > Settings > Advanced > SSO
Click "Create New SSO Configuration"
Select "Embedded" as the SSO type
Save the generated secret token - you'll need this for the technical setup

B. Custom Fields Configuration

Go to Admin > Advanced > Custom Fields
Click "Create New"
For Entity Type, select either:
- User (for user-specific fields)
- Customer Account (for account-level fields)
Select "Menu" as the field type (only supported type)
Configure your menu options
Save the field configuration
Note the API name of your custom field - you'll need this for the integration status

C. Integration Status Setup

Navigate to Admin > Customers > Integration Status
Create your statuses from the following status types:
- Active (for fully configured integrations)
- Pending (for incomplete setup)
- Disabled (for inactive integrations)
- Error (for failed configurations)

D. Dynamic CTA Setup

Go to Listing > Edit > Dynamic CTAs
Click "Create New CTA"
Configure CTAs using:
- Integration statuses (from step C)
- Custom fields (from step B)

More details here: https://help.partnerfleet.io/docs/dynamic-ctas-configuration

Part 2: Technical Implementation

A. JWT Token Generation

# Configuration
key = ENV["INAPPKEY"]  # This should be the secret token from Part 1.A

# Generate JWT token
def generate_jwt_token(user, account)
  begin
    data = {
      "email": user.email + user.id.to_s,
      "ufn": user.first_name,
      "uln": user.last_name,
      "account": {
        "external_id": account.id,
        "name": account.name,
        # Account custom fields go directly in account object
        # Custom field names should be alphanumeric with no spaces
        "tier": account.tier&.strip  # Ensure clean data
      },
      # User custom fields go in fields object
      "fields": {
        "userType": user.user_type&.strip
      },
      "exp": (Time.zone.now + 5.minute).to_i
    }
    
    JwtAuthenticator.encode(data, key)
  rescue => e
    Rails.logger.error("JWT generation failed: #{e.message}")
    raise "Authentication token generation failed"
  end
end

More details here: https://help.partnerfleet.io/docs/jwt-sso-implementation

B. Integration Status Format

The integration status JSON requires this structure:

{
  "integrations": [
    {
      "partner_id": "string",    // Required: Integration identifier
      "status": "string",        // Required: "Created", "Pending", "Disabled", "Error"
      "metadata": {              // Optional: Additional data
        "last_sync": "ISO8601",  // Optional: Last sync timestamp
        "error_message": "string" // Optional: Error details
      }
    }
  ]
}

Example Implementation:

def generate_integration_status(records)
  records.each_with_object([]) do |record, array|
    status = if record.enabled && record.setup_complete
               'Created'     # Active/Complete
             elsif record.enabled
               'Pending'     # Incomplete setup
             else
               'Disabled'    # Inactive
             end

    array << {
      partner_id: record.integration.external_id,
      status: status
    }
  end
end

Usage Example:

{
  "integrations": [
    {
      "partner_id": "partner123",
      "status": "Created"
    }
  ]
}

More details here: https://help.partnerfleet.io/docs/dynamic-ctas-configuration

C. Frontend Implementation

<!-- Container for the iframe -->
<div class="w-100" id="iframe-container"></div>

<!-- Core script -->
<script src="YOURINAPPURL/inapp_script.js" 
        data-turbo-track="reload" 
        data-turbo-eval="false"></script>

<!-- Implementation script -->
<script>
    function initializeIframe() {
      embeddedIframeInstance = new EmbeddedIframe({
        // Base URL for the iframe content
        iframeOrigin: 'YOURINAPPURL',

        // Security: Allowed origins for communication
        trustedOrigins: ['YOURINAPPURL'],

        // DOM element to mount the iframe
        containerId: 'iframe-container',

        // Initial authentication token
        initialToken: '<%= @jwt_token %>',

        // Integration status data
        integrations: <%= raw(@integration_details.to_json) %>,

        // Additional configuration
        urlVariables: { domain: window.location.origin },

        // Token refresh handler with retry logic
        getJwtToken: function() {
          // Method to obtain a new JWT if necessary
        }
    	});
    });
</script>

More details here: https://help.partnerfleet.io/docs/embed-script-implementation