Integráció fejlesztése harmadik feleknek

Ez a fejezet fejlesztőknek szól: a 6.0-s hozzájárulás-kezelési szerkezetet írja le, és azt, hogyan készíthetsz saját bővítményedhez integrációt.

Hozzájárulás-kezelés

A Complianz a hozzájárulási műveleteket JavaScript-függvényekkel és hookokkal kezeli. A PHP használata azért kockázatos, mert gyorsítótárazott oldalakon a PHP nem fut le. Ha mégis PHP kell, a shortcode átirányítással oldja meg a gyorsítótár-problémát (lásd Hozzájárulási terület).

A 6.0-tól több hook átnevezésre vagy megszüntetésre került. A megszűnt és módosult hookok a cookiebanner/js/migrate.js fájlban találhatók, és a hookok több információt adnak át. Ha a bővítményt a 6.0 előtti verzióval használtad, a Complianz alapból bekapcsolja a migrate.js fájlt. Ha nincs szükséged a régi integrációkra, vagy már frissítetted őket, a beállításokban kikapcsolhatod.

Ajánlott a Complianz szolgáltatásait közvetlenül a Complianzba integrálni: helyőrzőt, felismerhető szolgáltatást és függőségeket állíthatsz be, a szkripteket pedig blokkolólistára teheted, így a megfelelő kategória szerint indulnak el. A sütiváltozók közvetlen olvasását nem ajánljuk, mert a sütik előtagja változhat (például multisite-nál a gyökéren cmplz_rt_).

Régi és új sütik

5.x süti	Értékek	6.x
cmplz_choice	set, üres	cmplz_status_saved_once: true, üres
cmplz_consent_status	allow, deny, üres	megszűnt
cmplz_statistics-anonymous	allow, deny, üres	megszűnt

A 6.0-tól használt sütik

Süti	Tartalma
cmplz_functional, cmplz_preferences, cmplz_statistics, cmplz_marketing	allow, deny vagy üres
cmplz_policy_id	az elfogadott sütiszabályzat aktuális verziója
cmplz_consented_services	az engedélyezett vagy tiltott szolgáltatások listája
cmplz_user_data (munkamenet-tároló)	a látogatóhoz tartozó sütisáv-beállítás
cmplz_id	a hozzájárulás követése a hozzájárulási nyilvántartáshoz és A/B teszthez
cmplz_saved_categories, cmplz_saved_service	annak ellenőrzése, hogy kell-e frissítési jelet küldeni a nyilvántartásnak vagy A/B tesztnek
usprivacy	a TC-karakterlánc az amerikai CCPA-hoz
cmplz_tcf_consent (helyi tároló)	a TC-karakterlánc a TCF-hez

Új szűrők

• cmplz_statistics_script_classes (osztályok tömbje)
• cmplz_statistics_category (kategória szövegként)
• cmplz_script_class
• cmplz_service_category

Adatattribútumok a hozzájárulást igénylő szolgáltatásokhoz

A korábbi verzióban a marketinghez kötött szolgáltatások cmplz-script, a statisztikához kötöttek cmplz-stats, a blokkolatlan szkriptek cmplz-native osztályt kaptak. A 6.0-tól adatattribútum jelzi a szükséges kategóriát, és ha ismert a szolgáltatás neve, szolgáltatásra is engedélyezhető:

Régi osztály	Új attribútum
cmplz-native	data-category="functional"
cmplz-stats	data-category="statistics"
cmplz-script	data-category="marketing"

<iframe data-category="marketing" data-service="youtube"></iframe>

<script type="text/plain" data-category="statistics" data-service="matomo"></script>

JavaScript-függvények

Függvény	Mit csinál
cmplz_has_consent(category)	Igaz, ha van hozzájárulás a kategóriához vagy szolgáltatáshoz
cmplz_get_banner_status()	A sütisáv állapota: elvetve vagy megjelenítve
cmplz_set_banner_status(status)	Beállítja a sütisáv állapotát (megjelenik vagy elvetett), és sütiben tárolja; a paraméter nem kötelező

Hookok

document.addEventListener("cmplz_enable_category", cmplz_my_custom_hook);
function cmplz_my_custom_hook(consentData) {
  let category = consentData.detail.category;
  let region = consentData.detail.region;
  let acceptedCategories = consentData.detail.categories;

  if (category === 'marketing') {
    // marketing hozzájárulással kapcsolatos teendő
  }
}

A legfontosabb hookok:

Hook	Mikor fut le
cmplz_before_cookiebanner	a sütisáv futása előtt
cmplz_enable_category	egy kategória engedélyezésekor (átadja a kategóriát, a kategóriákat és a régiót)
cmplz_tag_manager_event	Tag Manager eseménynél (a kategóriát adja át)
cmplz_run_after_all_scripts	az összes szkript betöltése után (a kategóriát adja át)
cmplz_cookie_banner_data	a sütisáv betöltésekor (a Complianz konfigurációs objektumát adja át)
cmplz_cookie_warning_loaded	a sütisáv teljes betöltése után (a régiót adja át)
cmplz_status_change	az állapot változásakor (kategória, kategóriák, régió)
cmplz_revoke	a hozzájárulás visszavonásakor (átadja, hogy kell-e újratöltés)

Saját JavaScript-kódrészlet hozzájáruláshoz kötése

Ha saját JavaScriptet teszel az oldalra, amelynek csak bizonyos hozzájárulás után szabad lefutnia, három lehetőséged van:

1. Add a kódot a Szkriptközpont (Script Center) első kódmezőjébe, vagy aszinkron kódnál a másodikba.
2. Használd a Google Tag Managert, és a Complianz eseményindítóit (lásd Tag Manager kategóriák beállítása).
3. Add hozzá a kódot, ahogy akarod, és módosítsd a kódrészletet úgy, hogy a Complianz kezelje.

A harmadik módszer a következő. A 6.0-tól az attribútumokat használd (lásd fent az adatattribútumokat); a régi osztályos megoldás is működik a visszafelé kompatibilitás miatt:

• Ne blokkolja a Complianz hozzájárulás előtt: a szkriptcímkére class="cmplz-native" kerül, például <script type="text/javascript" class="cmplz-native">.
• Statisztikai hozzájárulásig blokkolja: class="cmplz-stats" és type="text/plain", például <script type="text/plain" class="cmplz-stats">.
• Marketinghozzájárulásig blokkolja: class="cmplz-script" és type="text/plain", például <script type="text/plain" class="cmplz-script">.

Példa egy Facebook-pixelre, amely csak marketinghozzájárulás után fut:

<script type="text/plain" class="cmplz-script">
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '{a-te-pixel-azonositod}');
  fbq('track', 'PageView');
</script>

Az eredeti, blokkolatlan kód ugyanez a <script> nyitócímkével, type és class nélkül.

A cmplz_event_all esemény megszűnése

A cmplz_event_all esemény a Tag Manager kategóriáinál használt egyéni esemény: a marketinghez kapcsolódó címkéket indítja, és a nem Tag Manageres oldalakon a konzolnaplóban is látszhat harmadik fél szkriptjeinek aktiválásakor. Ez az esemény megszűnik, és a cmplz_event_marketing váltja fel. Az új esemény már használható. A cél ugyanaz marad, csak a név változik. A 4.6.0-tól a böngészőkonzolban, ha az esemény használatban van, ez az üzenet jelenik meg:

Deprecated event: The cmplz_event_all event will be deprecated in the future.

Ha a Tag Managerben a cmplz_event_all az indító, cseréld cmplz_event_marketing-ra. A Tag Manager kategóriáiról a Tag Manager kategóriák beállítása fejezet szól.

Saját JavaScript-kódrészlet hozzájáruláshoz kötése

Ha saját JavaScriptet teszel az oldalra, amelynek csak bizonyos hozzájárulás után szabad lefutnia, három lehetőséged van:

1. Add a kódot a Szkriptközpont (Script Center) első kódmezőjébe, vagy aszinkron kódnál a másodikba.
2. Használd a Google Tag Managert, és a Complianz eseményindítóit (lásd Tag Manager kategóriák beállítása).
3. Add hozzá a kódot, ahogy akarod, és módosítsd a kódrészletet úgy, hogy a Complianz kezelje.

A harmadik módszer a következő. A 6.0-tól az attribútumokat használd (lásd fent az adatattribútumokat); a régi osztályos megoldás is működik a visszafelé kompatibilitás miatt:

• Ne blokkolja a Complianz hozzájárulás előtt: a szkriptcímkére class="cmplz-native" kerül, például <script type="text/javascript" class="cmplz-native">.
• Statisztikai hozzájárulásig blokkolja: class="cmplz-stats" és type="text/plain", például <script type="text/plain" class="cmplz-stats">.
• Marketinghozzájárulásig blokkolja: class="cmplz-script" és type="text/plain", például <script type="text/plain" class="cmplz-script">.

Példa egy Facebook-pixelre, amely csak marketinghozzájárulás után fut:

<script type="text/plain" class="cmplz-script">
  !function(f,b,e,v,n,t,s)
  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
  n.queue=[];t=b.createElement(e);t.async=!0;
  t.src=v;s=b.getElementsByTagName(e)[0];
  s.parentNode.insertBefore(t,s)}(window, document,'script',
  'https://connect.facebook.net/en_US/fbevents.js');
  fbq('init', '{a-te-pixel-azonositod}');
  fbq('track', 'PageView');
</script>

Az eredeti, blokkolatlan kód ugyanez a <script> nyitócímkével, type és class nélkül.

A cmplz_event_all esemény megszűnése

A cmplz_event_all esemény a Tag Manager kategóriáinál használt egyéni esemény: a marketinghez kapcsolódó címkéket indítja, és a nem Tag Manageres oldalakon a konzolnaplóban is látszhat harmadik fél szkriptjeinek aktiválásakor. Ez az esemény megszűnik, és a cmplz_event_marketing váltja fel. Az új esemény már használható. A cél ugyanaz marad, csak a név változik. A 4.6.0-tól a böngészőkonzolban, ha az esemény használatban van, ez az üzenet jelenik meg:

Deprecated event: The cmplz_event_all event will be deprecated in the future.

Ha a Tag Managerben a cmplz_event_all az indító, cseréld cmplz_event_marketing-ra. A Tag Manager kategóriáiról a Tag Manager kategóriák beállítása fejezet szól.

Shortcode paraméterek

A hozzájárulási terület shortcode-jának paraméterei: cache_redirect (false vagy true), category (például marketing) és text (a helyőrző szövege). A teljes lista a Hozzájárulási terület fejezetben van.

PHP

// igaz, ha van hozzájárulás a kategóriához
cmplz_has_consent( $category );

Saját integráció létrehozása

Az integrációs API-val a felhasználó teljes kontrollt kap: az integráció megjelenik az integrációs központban, ahol bekapcsolhatja, vagy a helyőrzőt be- és kikapcsolhatja. A példa egy Google Maps bővítmény (MapPress).

1. Az integráció bejelentése

Add hozzá a bővítményed az integrációkhoz a cmplz_integrations szűrővel. A példában a MapPress konstansa jelzi, hogy a bővítmény aktív; ez lehet függvény vagy osztálynév is, de a bővítmény fő fájljában kell deklarálni, különben a Complianz nem észleli.

function my_plugin_integration( $cmplz_integrations_list ) {
    $cmplz_integrations_list['mappress'] = array(
        'constant_or_function' => 'Mappress',
        'label'                => 'MapPress Maps for WordPress',
        'firstparty_marketing' => false,
    );
    return $cmplz_integrations_list;
}
add_filter( 'cmplz_integrations', 'my_plugin_integration' );

2. Az integrációs fájl helye

Mondd meg a Complianznak, hol van az integrációs fájl. A $plugin az integrációs tömb kulcsa (itt mappress). Hozz létre a bővítményedben egy fájlt (például complianz.php), és add meg az útvonalát. Így a Complianz be tudja tölteni, és az integrációs áttekintőből a Complianz vagy a bővítmény kikapcsolása nélkül is kikapcsolható.

function my_plugin_integration_path( $path, $plugin ) {
    if ( $plugin === 'mappress' ) {
        return 'my_plugin_path/complianz.php';
    }
    return $path;
}
add_filter( 'cmplz_integration_path', 'my_plugin_integration_path', 10, 2 );

3. Az integráció elkészítése

A fájl elején védd a közvetlen elérést:

<?php
defined( 'ABSPATH' ) or die( "you do not have access to this page!" );

Szkript blokkolásához a cmplz_known_script_tags szűrővel új elemet adsz a tömbhöz. Minden olyan URL-t, amelyet hozzájárulás nélkül blokkolni kell, az urls indexbe tegyél: lehet beágyazott szkript részlete vagy a forrás URL-jének egy egyedi része. Az új elemnek mindig kell neve, kategóriája és legalább egy URL-je.

function cmplz_mappress_script( $tags ) {
    $tags[] = array(
        'name'               => 'mappress',
        'category'           => 'marketing',
        'urls'               => array(
            'mappress-google-maps-for-wordpress/js/mappress',
        ),
        'enable_placeholder' => '1',
        'placeholder'        => 'google-maps',
        'placeholder_class'  => 'mapp-canvas-panel',
        'enable_dependency'  => '0',
    );
    return $tags;
}
add_filter( 'cmplz_known_script_tags', 'cmplz_mappress_script' );

Helyőrző hozzáadása

A példában a meglévő google-maps helyőrzőt választottuk. Az összes helyőrző a bővítmény assets/images/placeholders mappájában található. A mapp-canvas-panel osztály rakja a képet a div-re, ezért egyedinek kell lennie. Az enable_placeholder értéke 1, a placeholder_class az osztály.

Saját helyőrzőt is megadhatsz: a cmplz_placeholder_<szolgáltatás> szűrő felülírja az images/placeholders mappa tartalmát. Átadja az észlelt forrást és a javasolt újat, te egészen mást is visszaadhatsz.

function cmplz_google_maps_placeholder( $new_src, $src ) {
    // az egyedi helyőrző útvonala
    return $new_src;
}
add_filter( 'cmplz_placeholder_google-maps', 'cmplz_google_maps_placeholder', 10, 2 );

Itt egy kis egyedi CSS is kell, hogy a helyőrző jól jelenjen meg:

function cmplz_mapppress_css() {
    ?>
    .mapp-main .cmplz-placeholder-element {
        height: 100%;
        width: 100%;
    }
    <?php
}
add_action( 'cmplz_banner_css', 'cmplz_mapppress_css' );

Egyedi elemek és webkomponensek. A helyőrző bármilyen érvényes HTML-elemhez kapcsolható, egyedi elemekhez és webkomponensekhez is (például <mappress-map>). A címkét nem kell sehol regisztrálni: ha az elemnek megvan a szkriptcímkében megadott placeholder_class, a Complianz hozzájárulás hiányában arra teszi a helyőrzőt.

add_filter( 'cmplz_known_script_tags', function( $tags ) {
    $tags[] = [
        'name'               => 'my-service',
        'category'           => 'marketing',
        'placeholder'        => 'google-maps',
        'urls'               => [ 'my-service.com' ],
        'enable_placeholder' => '1',
        'placeholder_class'  => 'my-widget-class',
    ];
    return $tags;
} );

<my-widget class="my-widget-class">
  Minden, ami itt van, a helyőrző mögött rejtve marad,
  amíg a látogató nem járul hozzá.
</my-widget>

A szolgáltatás felvétele

Ez nem kötelező, de hasznos: ha hozzáadod ezt a szűrőt, a bővítmény automatikusan felveszi a „Google Maps” szolgáltatást az észlelt szolgáltatások közé, így alapértelmezetté válik, és megjelenik a róla szóló értesítésben. A közösségi médiához a cmplz_detected_social_media, a statisztikához a cmplz_detected_stats_type hook tartozik.

function cmplz_mappress_detected_services( $services ) {
    if ( ! in_array( 'google-maps', $services ) ) {
        $services[] = 'google-maps';
    }
    return $services;
}
add_filter( 'cmplz_detected_services', 'cmplz_mappress_detected_services' );

Függőségek

Néha a szkriptek hozzájárulás után rossz sorrendben töltődnek be, és JavaScript-hibát okoznak („undefined function”, „undefined constant”). Ilyenkor megadhatod, melyik szkript melyikre várjon. A példában a wpgmp_map részletet tartalmazó beágyazott szkriptnek meg kell várnia a maps.js fájlt, mert az onnan vár egy változót. Állítsd az enable_dependency értékét 1-re, és add meg a dependency tömböt ('a-szkript-amire-varni-kell' => 'a-varakozo-szkript' párokkal). A részletnek elég egyedinek kell lennie.

function cmplz_mappress_script( $tags ) {
    $tags[] = array(
        'name'               => 'mappress',
        'category'           => 'marketing',
        'placeholder'        => 'google-maps',
        'urls'               => array(
            'mappress-google-maps-for-wordpress/js/mappress',
        ),
        'enable_placeholder' => '1',
        'placeholder_class'  => 'mapp-canvas-panel',
        'enable_dependency'  => '1',
        'dependency'         => [
            'maps.js' => 'wpgmp_map',
        ],
    );
    return $tags;
}
add_filter( 'cmplz_known_script_tags', 'cmplz_mappress_script' );

Így teljes értékű integrációt kapsz, amely a Complianz integrációs vezérlőpultján kezelhető. A MapPress és más integrációk teljes kódja a Complianz bővítménymappájában, az integrations/plugins alatt található.