Localizing Interactions

Download and localize interactions and be prepared for unexpected interruptions!

Description

When relying on third party API’s and services to handle and deliver inquiries, you must be prepared for unexpected interruptions!

Implementation

Assuming that you have already created a strategy and it’s modules, the following will help you understand the necessary steps.

Downloading and localize modules using the Form Synergy’s API client


use \FormSynergy\Init as FS;
/**
 * Have the following ready: */
 $profileid = ''; 
 $modid     = ''; // Strategy id.
 
$api = FS::Api()->Load($profileid);

// Create a new resource storage to store responses
 
$resource = FS::Resource('response');

// Retrieve strategy details
$api->Get('strategy')
    ->Where([
        'modid' => $modid
    ])
    ->As('strategy');

$resource
    ->Store( 'strategy' )
    ->Data( $api->_strategy() );


// Download modules within the strategy.
$api->Download('strategy')
    ->Where([
        'modid' => $modid
    ])
    ->As('modules'); // Store response data as modules.
    // To retrieve stored modules we can use $api->_modules();
 
/**
 * Store each module independently.
 **/  
foreach($api->_modules() as $module ) {

    /**
     * Note that the Form Synergy JS client renders interactions
     * using a virtual DOM technique, therefore modules do not 
     * consists nor contain any HTML! */
     $resource
        ->Store( $module['moduleid'] ) // The name of the module.
        ->Data( $module ); // Let's store the entire entry.
}
    

Providing the JS client an alternative endPoint

The JS client is equipped to check for unexpected connection problems with the FS service. If local mode is enabled, requests, will be handled locally until connection problems are resolved.


/**
 * Instantiate the Form Synergy class. */ 
 const FS = new FormSynergy();

/**
 * Enable heartbeat feature. */      
 FS.heartBeat(10000); 

/**
 * Enable localMode. */      
 FS.setLocalMode({
    endPoint: '', //Where to send request
    request: {
        key: 'value' // Passing additional data to the request
    },
    response: {
        'success': 'Successful response',
        'error': 'Error response'
    },
}); 

            

Properly responding to a localized request

The JS client is expecting a response that contains interaction data including a DomObject. The below example response, is what the JS client is expecting.

 
/**
 * Check for incoming POST requests. */
 if( !isset( $_POST ) ) {
     
    return;
 }

/**
 * Handle notifications.
 * This is an example function, it can be replaced by anything. 
 * It's purpose is to notify the administrator of any inquiries. */
 function handle_response( $options, $request, $responses ) {

    // Some mail_function();
    return mail_function() ? $response['sent'] : $response['fail'];
 }

/**
 * Handle requests */
 function handle_requests() {

    /**
     * Default response */
     $return = [
        'response'  => 'error',
        'message'   => 'The requested module is not localized.'
     ];

    /**
     * Retrieve requests created by the JS client */ 
    $request = json_decode( file_get_contents( 'php://input' ) );

    /**
     * Switch between request types */
    switch ( $request->api ) {

        // Event requests are associated with modules
        case 'event':
            // Load strategy details
            $strategy = $resource->Get( 'strategy' );

            // Retrieve the stored module.
            $module = $resource->Get( $request->set->trigger->moduleid );

            // If the module exists
            if ( $module ) {
            
                // Return the response
                $return = [
                    'dataType'  => 'DomObject',
                    'el'        => '@' . $request->set->trigger->moduleid,
                    'etag'      => ':' . str_replace( ' ', '_', $module['name'] ) . '@' . str_replace( ' ', '_', $strategy['name'] ),
                    'DomObject' => $module['DomObject'],
                    'id'        => $request->set->trigger->moduleid,
                    'opt'       => $request->set->opt,
                    'response'  => 'success',
                    'trigger'   => $request->set->trigger,
                    'target'    => $request->set->target,
                    'rm'        => false,
                    'display'   => false
                ];
            }

            break;

        // Interaction requests are associated with inquiries.
        case 'interaction':

            $options = [
                'recipient_name'    => '',
                'recipient_email'   => '',
                '...' => ''
            ];

            $return = [
                'objective'     => $objective,
                'response'      => 'success',
                'message'       => 'onsubmit' == $request->set->action_type 
                                    ? 'Dismissed' 
                                    : handle_response( $options, $request , [
                                        'sent' => 'Notification sent',
                                        'fail' => ''
                                    ]
                ),
                'dataType'      => 'fs-message', 
                'fsMessage'     => 'Thank You',
                'rm'            => $module->moduleid
            ];

            break;
    }
    echo json_encode( $return );
 }