Data privacy API
This page describes the API for handling personal data protection tasks if you are developing a custom module in Java. The API is applicable also for the purposes of GDPR – General Data Protection Regulation (Regulation (EU) 2016/679). The API covers two areas of personal data protection: handling visitor consent and managing cookies.
Handling visitor and consent information
To use the visitor API, make sure that your project depends on the Visitor manager module:
info.magnolia.consent.visitor.VisitorManager and
info.magnolia.consent.visitor.Visitor are the central
interfaces needed for handling visitor information. The
magnolia-privacy-visitor-manager module provides a JCR-based
implementation for VisitorManager
(info.magnolia.consent.visitor.impl.JcrBasedVisitorManager),
which stores data in the JCR visitors workspace.
Getting VisitorManager
info.magnolia.consent.visitor.VisitorManager is a singleton. To get an instance, inject it in the public constructor of the class where you want to use it.
package info.magnolia.documentation.gdpr;
import info.magnolia.consent.visitor.VisitorManager;
import javax.inject.Inject;
public class MyClass {
private final VisitorManager visitorManager;
@Inject
public MyClass(VisitorManager visitorManager){
this.visitorManager = visitorManager;
}
}Line 11: Assigns the injected VisitorManager to the private final class member variable.
Getting a visitor
Use info.magnolia.consent.visitor.Visitor to get a visitor.
Visitor visitor = visitorManager.getVisitor("visitor@example.com");Getting all references to a visitor
Set<PrivateRecordReference> references = visitorManager.getReferences(visitorManager.getVisitorIdForRequest());Deleting all visitor data
// delete the visitor data by a given visitor id; done in two steps for security reasons
// request deletionId
String deletionId = visitorManager.requestVisitorDeletion("visitor@example.com");
// delete the visitor by deletionId
visitorManager.confirmDeletion(deletionId);| Deleting visitor data is done usually upon a request coming from a consent confirmation link (sent via email). |
Getting consent source
The source can be a URL, an email address or a phone number where the last consent update came from.
String source = consent.getSource();
Checking consent status
Consent status may be given, denied or withdrawn.
Consent.ConsentStatus consentStatus = consent.getFields().get("email");
Updating consent
The following example changes the previous consent status to given
with an expiration of one month:
Calendar expire = Calendar.getInstance();
expire.add(Calendar.MONTH, 1);
ConfiguredConsent.builder()
.source("mailto:visitor@example.com")
.field("email", Consent.ConsentStatus.given)
.expire(expire)
.build();Managing cookies
To use the Cookie manager API make sure that your project depends on the Cookie manager module:
To handle cookies on the server side, Magnolia provides info.magnolia.consent.cookie.CookieManager. The Cookie manager knows about a website visitor’s consent that is related to cookies.
|
Instead of utilizing the java core cookie API, we recommend using the Cookie manager since the manager only adds cookies upon consent given by a website visitor. |
Getting CookieManager
The Cookie manager implementation is a singleton. To get an instance, inject it in the public constructor of the class where you want to use it.
import info.magnolia.consent.cookie.CookieManager;
public class CookieBox {
private final CookieManager cookieManager;
public CookieBox(CookieManager cookieManager) {
this.cookieManager = cookieManager;
}
public void doSomething {
// use the cookieManager according do your needs
}
}Line 7: Assign the injected cookieManager to private final class member variable.
Getting a cookie from a request
Signature
Optional<Cookie> getCookieFromRequest(CookieDefinition cookieDefinition);Example
public Cookie getCookie(String cookieId){
if(cookieManager.getCookieDefinition(cookieId).isPresent()){
return cookieManager.getCookieFromRequest(cookieManager.getCookieDefinition(cookieId).get()).orElse(null);
}
return null;
}The method returns the cookie object or null by a given
cookie ID.
Adding a cookie
Adding a cookie with the Cookie manager requires info.magnolia.consent.cookie.definition.CookieDefinition. You can get a cookie definition as defined in the Cookies app with the Cookie manager, see getting and adapting a cookie definition.
| The cookie is only added if the website visitor has given consent for the cookie. |
Signature
void addCookie(CookieDefinition cookieDefinition)Example
public void setMonsterCookie(String value) {
if (cookieManager.getCookieDefinition(MONSETRCOOKIE_ID).isPresent()) {
CookieDefinition cookieDefinition = cookieManager.getCookieDefinition(MONSETRCOOKIE_ID).get();
cookieDefinition.setValue(value);
cookieManager.addCookie(cookieDefinition);
}
}Line 4: You can override properties of the definition coming from the Cookies app.
Checking consent for a cookie
The method checks whether the website visitor has given consent for a potential cookie. You need info.magnolia.consent.cookie.definition.CookieDefinition to check for consent. Also, read Understanding the decision whether a cookie is set or not, which explains the check consent mechanism for a specific cookie.
Signature
boolean isCookieConsented(CookieDefinition cookieDefinition)Example
public boolean monsterCookieConsented() { return cookieManager.getCookieDefinition(MONSETRCOOKIE_NAME).isPresent() && cookieManager.isCookieConsented(cookieManager.getCookieDefinition(MONSETRCOOKIE_NAME).get()); }
Getting a cookie definition
The method returns info.magnolia.consent.cookie.definition.CookieDefinition by a given cookie ID.
You need
info.magnolia.consent.cookie.definition.CookieDefinition
instances as arguments for the #addCookie and
#isCookieConsented methods of the Cookie
manager.
Returned cookie definitions are those managed with the Cookies app. The Cookie manager always returns a clone of the definition as configured in the Cookies app. This means that you also can override properties of the cookie definition as set in the Cookies app.
Signature
Optional<CookieDefinition> getCookieDefinition(String cookieId)Example
public CookieDefinition getMonsterCookieDefinition(){
return cookieManager.getCookieDefinition("monsterCookie").orElse(null);
}