ACONA
Search…
ACONA
About
User Documentation
Developer documentation
ACONA Data Warehouse
Styleguide
Creating CMS integrations
FAQs
Powered By GitBook
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. 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. 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.

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 [email protected]

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 [email protected]

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
  1. 1.
    A list of analysed urls with latest Score (max 5 for now). MVP. ----
    ​https://www.acona.app/ 60
    ​https://www.acona.app/about 80
    ​https://www.acona.app/metrics 70
    ​https://www.acona.app/info 20
    ​https://ww.acona.app/legal 20
    ---
  2. 2.
    Latest Score at URL/page detail infos
  3. 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}]
​

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:
---
  • 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)
---

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.
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";
​
​

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).
Previous
Styleguide
Next
FAQs
Last modified 10mo ago
Copy link
Outline
How to set up the system
Your personal token
Data Sources and Services
Page types and Success Score Definitions
Domain and URLS
Show ACONA Success Scores
Display recommendations
API Requests
Required Settings in CMS
How to save/update data in CMS