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:
- 1.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.
- 2.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.
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 [email protected]
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.
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.
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 [email protected]
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
- 1.A list of analysed urls with latest Score (max 5 for now). MVP. -------
- 2.Latest Score at URL/page detail infos
- 3.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}]
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:
---
- RED ICON: RECOMMENDATION TEXT (list element)
- RED ICON: RECOMMENDATION TEXT (list element)
- YELLOW ICON: RECOMMENDATION TEXT (list element)
- YELLOW ICON: RECOMMENDATION TEXT (list element)
- GREEN ICON: RECOMMENDATION TEXT (list element)
- GREEN ICON: RECOMMENDATION TEXT (list element)
---
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.
curl -G "https://data.acona.app/rpc/recommendations_last" -d url=https://www.acona.app/about -d indication=red -d langcode=en -H "Authorization: Bearer $TOKEN";
curl -G "https://data.acona.app/rpc/recommendations_last" -d url=https://www.acona.app/about -d indication=yellow -H "Authorization: Bearer $TOKEN";
curl -G "https://data.acona.app/rpc/recommendations_last" -d url=https://www.acona.app/about -d indication=green -H "Authorization: Bearer $TOKEN";
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:
export TOKEN="<paste your token here>"
curl -G "https://data.acona.app/rpc/recommendations" -d url=https://www.acona.app/about -d date=2021-09-06 -d indication=red -H "Authorization: Bearer $TOKEN";
curl -G "https://data.acona.app/rpc/recommendations" -d url=https://www.acona.app/about -d date=2021-09-06 -d indication=yellow -H "Authorization: Bearer $TOKEN";
curl -G "https://data.acona.app/rpc/recommendations" -d url=https://www.acona.app/about -d date=2021-09-06 -d indication=green -H "Authorization: Bearer $TOKEN";
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.
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 modified 1yr ago