Developing CX Apps Content Services

This topic explains how to develop a content service for Eloqua Engage.

Developing a content service requires you to develop a Render URL endpoint. You will enter the URL location of this endpoint when you create your service in the CX App Manager.

After a user has installed your app, it appears in Eloqua Engage on the extensions sidebar.

When a user clicks your app, the app framework will then call your app's Render URL endpoint to display your app's HTML page in an inframe.

It's the responsibility of the app developer to:

• Develop the app's Render URL endpoint to open an iframe within Engage
• Send a post message to Eloqua to display the HTML content into the iframe

Render URL

The Render URL is called when a user within Eloqua Engage clicks the service to insert content into Engage. The entire process of calling this endpoint is outlined below.

1. An Eloqua Engage user clicks your app.
2. Engage returns a page that contains an iframe.

3. The app must implement a post message to notify Engage to display the app's content within the Engage iframe.

   window.parent.postMessage({
                               amsAction: "notifyProduct",
                               notifyProduct: "forward",
                               status: "approved",
                               serviceAction:'contentSelections',
                               payload: [
                                       {
                                           link: {
                                               name: "Selected Story1",
                                               url: "http://www.google.com"
                                           }
                                       }
                               ]
   

4. The iframe within Engage calls a public AMS endpoint requesting the service's configuration UI.

5. AMS returns a page with an iframe and Javascript for sending and receiving a MessageEvent using the postMessage() method.

   Example: The Javascript could resemble:

   var Remote = {
       init : function(onMetadata, onConfigSave, onProductResponse,
               onAppResponse) {
           var handler = function(e) {
               if (e && e.data) {
                   var data = e.data;
                   var requestId = data.requestId;
                   if (requestId) {
                       if (requestId == 'metadata') {
                           onMetadata(data);
                       } else if (requestId.startsWith('save')) {
                           onConfigSave(data);
                       } else if (requestId.startsWith('product')) {
                           onProductResponse(data);
                       } else if (requestId.startsWith('application')) {
                           onAppResponse(data);
                       }
                   }
               }
           };
           window.addEventListener("message", handler, false);
       },
       send : function(msg) {
           console.log('Sending', msg);
           window.parent.postMessage(msg, '*');
       },
       save : function(requestId, config) {
           var o = {
               amsAction : "save",
               payload : config
           };
    
           o['requestId'] = "save" + (requestId || "");
    
           Remote.send(o);
       },
       getMetadata : function() {
           var o = {
               amsAction : "metadata",
               requestId : "metadata"
           };
    
           Remote.send(o);
       },
       getFromProduct : function(requestId, url, requestType) {
           if (url) {
               var o = {
                   amsAction : "product",
                   destinationUrl : url,
                   requestType : requestType
               };
    
               o['requestId'] = "product" + (requestId || "");
    
               Remote.send(o);
           }
       },
       getFromApp : function(requestId, relativeUrl) {
           if (relativeUrl) {
               var o = {
                   amsAction : "application",
                   destinationUrl : relativeUrl,
                   requestType : 'POST'
               };
    
               o['requestId'] = "application" + (requestId || "");
    
               Remote.send(o);
           }
       }
   };

6. The iframe within the returned AMS page loads another AMS hosted URL.

7. AMS sends a HTTP POST request to the service's Render URL.

   Request sent by AMS to App

   Task	Method	Path
   Render service	POST	http://<service_base_url>/<service_render_url>

   Example

   POST https://app.awesomeapp.com/render
   Authorization: Bearer <JWT>
   
   {
     status: 'CREATED',
     locale: 'en-US',
     applicationServiceInstall: {
       uuid: 'b275f697-f3f1-4c9f-85db-07b1195b17c5',
       name: 'Content Service',
       description: 'A Content Service',
       invokeUrl: 'http://awesomeapp.com/services/444b0dc1-2ea3-47a1-87d5-e3baccc8447d/invoke',
       smallLogo: 'https://awesomeapp.com/images/logo_small.png',
       mediumLogo: 'https://awesomeapp.com/images/logo_medium.png',
       largeLogo: 'https://awesomeapp.com/images/logo_large.png',
       maxBatchSize: null,
       application: {
         baseUrl: 'https://awesomeapp.com',
         configureUrl: '/configure', 
         description: 'Awesome App Description',
         deleted: 0,
         installUrl: '/install',
         largeLogo: 'https://awesomeapp.com/images/logo_large.png',
         mediumLogo: 'https://awesomeapp.com/images/logo_medium.png',
         name: 'Awesome App',
         saveConfigurationUrl: '/saveConfigure',
         smallLogo: 'https://awesomeapp.com/images/logo_small.png',
         status: 'UP',
         publicationStatus: 'DEVELOPMENT',
         statusMessage: {
           "body": null,
           "eta": 0,
           "reason": null
         },
         statusUrl: '/status',
         uninstallUrl: '/uninstall',
         uuid: '5623f79a-8370-463d-b6c0-fc49e54daacc',
         providerUuid: '2ed3ad9c-db8d-41f1-ab62-5c764f65e3a2'
       },
       serviceType: {
         name: 'Content',
         externalName: 'Content',
         description: '',
         serviceTypeDefinition: {
           "fieldDefinitions": []
         }
       },
       supportedAssetTypes: [
         
       ],
       deleted: 0,
       installUuid: '7a4a92bd-c45e-49ba-9f51-a659207d739f',
       productName: 'SalesTools Engage Product',
       providerName: 'Demo Provider',
       supportedAssetTypeUuids: [
         
       ],
       status: 'UP'
     },
     assetType: null,
     assetId: null,
     recordDefinition: null,
     uuid: '19ad3f6f-fd72-4857-a7c9-6ef12c1e1864',
     secret: '12b05ef0-2e94-44f9-9828-fd716f0d987d-6bbe8548-8a99-4430-a61c-621dfd1dad06'
   }

8. The app responds with HTML. AMS could inspect the HTML, if needed.
9. The app framework returns the returned HTML to the user.

Learn more

Creating Content Services

Profiler Tab Services