Creating CMS integrations
How to create CMS integration for ACONA
The CMS integrations (e.g. for Drupal, WordPress, Neos) create a bridge between the CMS and the ACONA Open Source Suite. The idea is that scores and recommendations are shown directly there where editors create and maintain content (in the CMS).
In a simplified view ACONA consists of three components: A. The ACONA Backend: This is a central site where users can create an ACONA user and set up their ACONA system and define settings. For us it will be available under www.acona.app.
B. The ACONA Data Warehouse: Storage of the data with an API to query it. We have it running on data.acona.app.
c. The CMS: The website that is analyzed. Here data and recommendations are shown. This is where this ACONA CMS INTEGRATION comes in.
In the CMS basically we want to have two displays:
A block or element that lists all analysed urls with latest ACONA Success Score (and a link to a page for url detail infos if 2 is done). This is the MVP.
A page for url specific ACONA detail infos. This can be accessed by the block from 1. Ideally it is also reachable when visiting the URL or the URL backend view in the CMS. In Drupal this can be a tab like VIEW / EDIT / REVISIONS / ACONA.
How to set up the system
Your personal token
For accessing the ACONA data you need a personal JWT Token. It will be created for registered users at www.acona.app, but for now just write an e-mail to acona@acolono.com
Data Sources and Services
Currently we only support Matomo for querying success metrics like page views or visits. If you don’t have a matomo running for your page, we can set up mock data for you and you can skip this step. Services will be configured at www.acona.app.
Page types and Success Score Definitions
When logged in at www.acona.app you will be able to define your page types (e.g. frontpage, landingpage, product page). For every page type you can set up your personal Success Score definition by telling the system what metrics or combination of metrics are most important for you.
For example you can say that for landingpages a combination of Organic Clicks and a low Bounce Rate defines the score, and for product pages it is just a specific Conversion Rate.
For testing purpose we will not deal with different types of pages and only have an example Success Score definition.
Domain and URLS
Please define your domain and 5 URLs, you want to analyse in https://www.acona.app. Ideally these urls exist in your development environment. Alternatively write an email to acona@acolono.com.
Show ACONA Success Scores
The ACONA Success Score is a value from 0 and 100, and should represent how a page or URL is working out regarding its most important metrics. The higher the better.
Basically we have three displays of ACONA Success Scores
A list of analysed urls with latest Score (max 5 for now). MVP. ----
https://www.acona.app/about 80
https://www.acona.app/metrics 70
---
Latest Score at URL/page detail infos
A History of Scores for a specific url at URL/page detail info
Get all URLs by domain with latest Success Score:
Example query:
export TOKEN="<paste your token here>"
curl -G "https://data.acona.app/rpc/acona_urls_success" -d domain=https://www.acona.app -H "Authorization: Bearer $TOKEN";
Example result:
[{"url":"https://www.acona.app/about","date":"2021-09-03","value":80},{"url":"https://www.acona.app/metrics","date":"2021-09-05","value":70}]
Success Score by URL and date
Arguments:
url: The url for that the success score should be queried
from_date: optional, default is today minus 7 days
to_date: optional: default is today.
Example queries:
export TOKEN="<paste your token here>"
curl -G "https://data.acona.app/rpc/acona_success_scores" -d url=https://www.acona.app/about -H "Authorization: Bearer $TOKEN";
curl -G "https://data.acona.app/rpc/acona_success_scores" -d url=https://www.acona.app/about -d from_date=2021-08-28 -H "Authorization: Bearer $TOKEN";
curl -G "https://data.acona.app/rpc/acona_success_scores" -d url=https://www.acona.app/about -d from_date=2021-08-28 -d to_date=2021-08-29 -H "Authorization: Bearer $TOKEN";
Example result:
[{"date":"2021-08-29","url":"https://www.acona.app/about","value":50},
{"date":"2021-08-28","url":"https://www.acona.app/about","value":50}]
Display recommendations
Will be displayed at the URL detail info page. Recommendations have a priority, indicated by color:
Red: High priority
Yellow: Medium priority
Green: No priority, as no action is required.
The ACONA recommendations should be grouped by priority:
---
High priority (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details, open)
RED ICON: RECOMMENDATION TEXT (list element)
RED ICON: RECOMMENDATION TEXT (list element)
Medium priority (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details, open)
YELLOW ICON: RECOMMENDATION TEXT (list element)
YELLOW ICON: RECOMMENDATION TEXT (list element)
No action required (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details, closed)
GREEN ICON: RECOMMENDATION TEXT (list element)
GREEN ICON: RECOMMENDATION TEXT (list element)
---
API Requests
For the most current data Arguments:
Url: The url the recommendations should be listed for
Date: Day for which recommendation should be listed
Indication: By default all recommendations are shown. But you can also list just red, green or yellow indications.
Langcode: Language of recommendation texts. Default is “en”. Currently also German texts are supported.
Example result:
[{ "Indication":"green", // green, red, yellow. Main priority/status. "title":"Pagetitle", // title in requested language. "recommendation":"This page does have a page title. Good job!", // Recommendation text in requested language. "Date":"2021-09-06", // Date (Day) when this recommendation has been prepared. "more":”Mehr Infos zum Seitentitel: https://moz.com/learn/seo/title-tag”, // More information about this recommendation in requested language. "Category": “Metatags”, // A predefined category/label. This can be used to filter/mark recommendations even more. Not used right now. "Relevance": “Values between 1 and 3. The lower the more relevant. Having this we could mark more relevant recommendations even in a single indication. Not used right now. ” }] For a specific date:
Required Settings in CMS
Authentication: We need a way to store an authentication token. This token is needed to have access to the ACONA Data Warehouse (data.acona.app).
Domain: Data is retrieved by domain. As the domain from CMS can differ to the domain that has been set in the ACONA Administration (e.g. when with or without www, or for dev environments), it may be better to define it in the CMS. Can be by default the current CMS domain.
How to save/update data in CMS
Ideally data is cached or saved somehow in the CMS, so data is not requested from API on every request. In Drupal we will cache data in static cache. But it may also be a solution to store data in a database table.
Updating data: Data in the backend will be calculated/updated daily, probably around midnight. In the CMS it might be enough to update data at least once or twice a day. This can be done by cron for example.
I will be helpful to store the date when data has been updated lastly. This date can be shown to the user (in the backend, or also where data is presented as a small footer note).
Last updated