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);
}