Custom integration

Follow this guide to add 3rd party content to your web application using Prepr.

Introduction

When creating publications for your web application, you may want to reference content stored in an external system such as another CMS, legacy system, or eCommerce platform. With Prepr, you can easily use any 3rd party system as a remote content source by following the steps below.

Step 1: Set up your custom API endpoint

In this step you need to prepare the API endpoint so that Prepr can make the calls to your external system.

1. Make sure your custom API response conforms to the predefined structure and format as follows:

{
  "items" : [
    {
            "id" : "unique_reference_id",
            "created_on" : "2019-11-21T12:51:03+00:00",
            "changed_on" : "2019-12-21T12:51:03+00:00",
            "body" : "Title that will be displayed in Prepr",
            "description" : "Descrtiption text displayed with the title",
            "image_url" : "https://picsum.photos/200/30",
            "external_url" : "https://example.com/admin/edit/products/9387498273",
            "data" : {
                "key" : "value"
                // This key value array will be returned within the Content item response.
            }
        }
   ],
    "total" : 256
}

The response must contain the following fields:

• items — an array containing all attributes that should be available as remote content in Prepr. See the detailed attribute description in the table below.
• total returns — the total number of items available. The total value also depends on the search parameters applied.

2. (Optional) Define Headers, specific key-value pairs, to add authentication or filters on the API's end. Check out the remote source setup for more details.

To learn more about how Prepr interacts with the API endpoint, consider the following:

• Automatic synchronization. To keep your remote content constantly updated in Prepr, your custom API must support filtering on the last changed items. In this case, Prepr will call the API with a changed_since param to refresh your items every 15 minutes. For example, website.com/prepr/feed?changed_since=1583414373 (UTC timestamp).

• Pagination. The API must work with the skip and limit params to paginate params, and the API response should contain a maximum of 50 items. For example,
  

Page 1: {{url}}?skip=0&limit=50
Page 2: {{url}}?skip=50&limit=50
Page 3: {{url}}?skip=100&limit=50, etc.

• Search. To help editors search for a remote content item, Prepr calls the external system URL with the q param containing the editors' input, for example, website.com/prepr/feed?q=Looking%20for%20an%20item. In this case, the total response will be updated with the filtered number of matching items.

Step 2: Add the custom remote source in Prepr

Now that you’ve set up your custom API endpoint, proceed with the configuration in Prepr. You’ll need to connect Prepr to your external system using the API credentials. Learn more on how to add a custom remote source.

Step 3: Add remote content to your content item

Once you’ve connected to the external system and added the Remote content field to your model, you can add the remote content to a content item using the following steps:

1. Navigate to the Content tab and click on the desired content item from the list.
2. In the remote content section, click the button to add new items (in our example – Add product), search through the catalog and add the desired items to the content item.
3. Save and publish this content item to complete the setup.

Step 4: Retrieve remote content using the API

Now that you’ve added products from your external system to the content item, you can retrieve the corresponding data using the API. Please refer to the example code snippets below:

{
 Pages {
   items {
     content_integrations {
       key1
       key2 
     }
   }
 }
}

curl --location --request POST 'https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{ Pages { items { content_integrations { key1 key2 } } } }","variables":{}}'

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

const graphql = JSON.stringify({
query: "{ Pages { items { content_integrations { key1 key2 } } } }",
variables: {}
})
const requestOptions = {
method: 'POST',
headers: myHeaders,
body: graphql,
redirect: 'follow'
};

fetch("https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

// WARNING: For POST requests, body is set to null by browsers.
const data = JSON.stringify({
query: "{ Pages { items { content_integrations { key1 key2 } } } }",
variables: {}
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
  console.log(this.responseText);
}
});

xhr.open("POST", "https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

<?php
$client = new Client();
$headers = [
'Content-Type' => 'application/json'
];
$body = '{"query":"{ Pages { items { content_integrations { key1 key2 } } } }","variables":{}}';
$request = new Request('POST', 'https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

{
 "data": {
   "Pages": {
     "items": [
       {
         "content_integrations": [
           {
             "key1": "Value 01",
             "key2": "Value 02"      
           },
           {
             "key1": "Value 11",
             "key2": "Value 12"
           }
         ]
       }
     ]
   }
 }
}

That’s it. Now your web page includes 3rd party content. Prepr will synchronize your remote content automatically to keep it up to date.