The Intelligent Layouts API can be used to return a full page personalisation by providing multiple placements in its response allowing you to generate complex personalised spaces. Layouts can be configured in the back office - the layout key should be noted and used in the API calls.

Layouts - Generating recommendations

The layouts endpoint can be used to generate a personalised layout:

POST https://api.graphyte.ai/intelligentlayouts/v1/layouts/{layoutKey}/layout

Headers:
x-api-key=api key given at integration
x-brand-key=unique reference for brand
content-type=application/json

A sample request would be very similar to the request for the Recommend API but with type equal to “layout”

{
  "context": {
    "product": "Gaming",
    "category": "Slots",
    "page": {
      "url": "casino.graphytecasino.com/en",
      "title": "Slots page"
    },
    "channel": "Mobile"
  },
  "userId": "123456",
  "traits": {
    "contextId": "440q6fneh3k-0jot24y2k-76umam8"
  },
  "type": "layout"
}

A sample response would contain an array of areas which contain at least one placement. Placements may also be returned with a “dummy” attribute. This is used to show the order that they should appear in but not to dictate the content. For example this could be used when a portlet is rendered using external data (e.g. bingo schedule).

{
    "layout": {
        "layoutId": "c078768a-7bb9-4bb7-908b-2f007d3d3389",
        "layoutDateTime": "2020-02-26T22:01:50.529624",
        "result": [
            {
                "area": {
                    "index": 0,
                    "name": "recommended0",
                    "placement": {
                        "title": "Recommended for you",
                        "placementKey": "3cc6b9ce-613f-4b90-a8eb-3a1ee1b86ff6",
                        "result": [
                            {
                                "game": {
                                    "game_code": "blueprintdondmegaways",
                                    "score": 0.395489391928103,
                                    "formFactors": [
                                        "tablet",
                                        "mobile",
                                        "desktop"
                                    ],
                                    "gameType": "Blueprint",
                                    "name": "Deal or No Deal Megaways Jackpot King",
                                    "rank": 1
                                }
                            },
                          ...
                        ],
                        "explanation": {
                            "item": "game",
                            "game": {
                                "game_code": "lobby"
                            },
                            "reason": "most_popular"
                        }
                    }
                }
            },
            ...
        ]
    }
}

Creating / Editing Layouts via API

As the Admin system is fully API based you can always use the Layout API to create/edit/remove layouts yourself via API in the same way that you can configure them within admin.

This endpoint: https://api.graphyte.ai/intelligentlayouts/v1/layouts/{layoutKey} can be used to GET (read), POST (update), DELETE (delete). To create an initial layout POST to

https://api.graphyte.ai/intelligentlayouts/v1/layouts

e.g. to read a layout configuration:

GET https://api.graphyte.ai/intelligentlayouts/v1/layouts/{layoutKey}

Headers:
x-api-key=api key given at integration (please note that to interact with layout configuration a key with "User" or "Service" permissions is required. A "Public" api key will not be able to work)
x-brand-key=unique reference for brand
content-type=application/json

It may be worthwhile looking at the API calls that are used by Admin for guidance (and to GET an existing layout for inspriration) but the data structure is documented below:

Layout data model

areas: Ordered array of areas (decision groups) for processing:

max_placements: integer - max number of placements to return
min_placements: integer - min number of placements to return
name: string - name of the area
placements: Array of placements to consider:

• placementKey: string - placement key (unique identifier)
• placementTitle: string - name of the placement (for display in layout editor)
• title: string - title to be returned for this placement
• max_placements: integer - max number of placements to return
• min_placements: integer - min number of placements to return
• dummy: boolean - return content or not (or just return it as a placeholder)
• extra: dictionary - free-form dictionary to contain any content for this placement (could be used for example for translations)

cacheTime: integer - number of seconds to cache placement orders e.g. 86400 for 1 day
createdBy: string - name of the user that created the layout
createdDate: string - ISO datetime of the creation of the layout
dedupe: dictionary - logic for deduplication

• dedupeLogic: “none” or “topN”
• N: number of items (e.g. top 6)

lastModifiedDate: string - ISO datetime of the last change time
layoutKey: string - uuid generated as the unique identifier of the layout
layoutName: string - name of the layout
product: “Gaming”, “Sports” or “eCommerce”
safe_mode: boolean - return results using best efforts even if not all configuration rules are met

Open API Specification

Full API specification is available within the Developer Tools section of the back office.