WordPress plugin om vCards te downloaden na het scannen van een qr-code

Voor één van onze opdrachtgevers hebben we een ontwerp gemaakt voor visitekaartjes. Aangezien het visitekaartje een beetje een achterhaald medium lijkt te zijn voor het delen van je persoonsgegevens, hebben we deze een moderne feature gegeven. Het visitekaartje heeft een qr-code voor het ophalen van de persoonsgegevens in de vorm van een ‘vCard’. Door de qr-code te scannen krijgt je telefoon de gegevens van het visitekaartje ’toegestuurd’ en kun je deze opslaan in je Contacten.

We hebben ervoor gekozen om controle te kunnen houden op de data die de ontvanger krijgt. Met het scannen van de qr-code word je naar de website (van onze opdrachtgever) gestuurd, waarna de website regelt wat je te zien krijgt. Als er in de beheeromgeving van de website aan de betreffende medewerker een vCard-bestand is toegekend, krijgt de ontvanger deze als download toegestuurd. Bij wijzigingen in de gegevens kan eenvoudig een nieuwe vCard worden geüpload. De eerstvolgende ontvanger die het visitekaartje scant krijgt dan de nieuwe data.

Test hier mijn QR-code!

scan mijn vCard

Wil jij ook makkelijk contactgegevens kunnen delen?

In begrijpelijke taal, met voorbeelden in code-taal, leggen we uit hoe dit gemaakt is. Leuk om zelf te bouwen, maar je kan ook onze plugin downloaden en instellen op je eigen site!

Let op! Extra plugin Advanced Custom Fields is benodigd.

We gebruiken geen externe plugins om binnen de website een qr-code en/of een vCard te genereren (die zijn er wel). Door deze bestanden apart voor te bereiden en daarna toe te voegen als upload bij Media, blijft de website verder ‘schoon’.

Aangezien de opdrachtgever ook graag fysieke (gedrukte) visitekaartjes wilde, hebben we voor de qr-code een onlinedienst gekozen die een url kan omzetten naar een svg-bestand. SVG is makkelijk geschikt te maken voor drukwerk, doordat het opgebouwd is uit vector-informatie.
Voor de vCard hebben we op een telefoon een nieuw contact aangemaakt en deze vervolgens aan onszelf gestuurd als vcf-bestand. Daarna kun je het makkelijk uploaden. Er zijn online-diensten die een vCard voor je kunnen maken, maar in het kader van privacy: je weet dan niet wat er in de achtergrond met de informatie gebeurt.

Benieuwd naar de techniek? Lees dan verder!

[1] Setup van WordPress

Elke qr-code geeft een url terug die op dezelfde manier is opgebouwd:

www.<domeinnaam>.nl/vcard/<slug-medewerker>/.

Als een verzoek aankomt bij de website moet de website weten wat er moet gebeuren, anders krijg je een 404-pagina. Er moet een regel gemaakt worden waardoor de website de vCard-url herkent. Gebruik hiervoor de functie add_rewrite_rule().

add_action( 'init', 'nen_rewrite_rules_vcard' );
function nen_rewrite_rules_vcard() 
{        
        add_rewrite_rule(  'vcard/(.+?)/?$' , 'index.php?vcard=1&vcard_name=$matches[1]' , 'top' );
        # Go to your admin permalinks-page and click save to add the rewrite rule. 
        # You can also trigger a flush just once by uncommenting the function below (do it once!!).
        //flush_rewrite_rules();
}Code language: PHP (php)

Dit soort regels worden opgeslagen in de database. Om ook deze nieuwe rewrite rule te activeren, moet je tegen WordPress zeggen dat deze opnieuw moet worden opgeslagen. Dat kan door in de admin-omgeving bij Instellingen > permalinks de pagina opnieuw te bewaren. Je kan ook éénmalig de functie ‘flush_rewrite_rules()’ activeren.

Daarnaast moet je tegen WordPress zeggen dat er extra variabelen (query_var) zijn waarmee gewerkt gaat worden. In de functie add_rewrite_rule heb je kunnen zien dat we daarmee de gegevens van de url omzetten naar de variabelen ‘vcard’ en ‘vcard_name’. Nu moeten ze worden opgenomen in het lijstje met ’toegestane query_vars’.

add_filter( 'query_vars', 'nen_register_query_var_vcard' );
function nen_register_query_var_vcard( $vars ) 
{           
        $vars[] = 'vcard';
        $vars[] = 'vcard_name';
        return $vars;
}Code language: PHP (php)

Om het vcard-bestandstype ‘vcf’ te kunnen uploaden in de media van je website, moet ook deze worden toegevoegd aan het lijstje met ’toegestane bestandstypes’. Ook hebben we ‘svg’ toegevoegd om de qr-code als svg-bestand te kunnen uploaden in Media.

add_filter( 'upload_mimes', 'nen_vcard_enable_upload' );
function nen_vcard_enable_upload( $mime_types )
{
        $mime_types['vcf']      = 'text/vcard';
        $mime_types['vcard']    = 'text/vcard';
        $mime_types['svg']      = 'image/svg+xml'; // to display qr as svg
        return $mime_types;
}Code language: PHP (php)

Oké, nu accepteert WordPress wat we nodig hebben, maar hoe sturen we de bezoeker onze vCard? Lees verder hoe we dat doen …

[2] Als een qr-code gescand wordt

De randvoorwaarden zijn nu ingesteld in WordPress: er kan gewerkt gaan worden met de data. Hiervoor gebruiken we de action-hook ‘template_redirect‘. Deze hook wordt getriggerd nadat alle data geladen is, maar voordat we gaan beginnen met de visuele presentatie. We gebruiken de hook om de bezoeker door te sturen naar de url van het vCard-bestand. Eerst testen we of query_var ‘vcard’ bestaat en de waarde ‘1’ heeft. Dan weten we dat dit een vCard-url is.

(Eigenlijk kun je ook testen op ‘vcard_name’ en is de query_var ‘vcard’ overbodig, maar voor nu laten we het even zo.)

add_action( 'template_redirect', 'nen_redirect_to_file' );
function nen_redirect_to_file()
{
        if( get_query_var('vcard') == '1' )
        {
                // do vcard stuff
        }
}Code language: PHP (php)

Daarna volgt het opvragen van een medewerker met de ‘slug’ zoals deze via de url is ontvangen. De slug moet gelijk zijn aan de waarde van het veld ‘vcard_name’ van een medewerker om een match te vinden. Uiteindelijk hebben we van de medewerker alleen de ID nodig waarmee we een ander meta-veld kunnen opvragen dat hoort bij deze medewerker (do user stuff).

Note: We hebben onze medewerkers opgeslagen als users in de user-tabel. Een nieuwe user/medewerker kun je aanmaken in de beheeromgeving onder de menuknop ‘gebruikers’. De benodigde velden voor het opslaan van de data leggen we uit bij punt 3.

// do vcard stuff
# set variables
$user_obj   = null;
$user_id    = null;
$vcard_id   = null;
$url        = null;

# do a search for user by meta field vcard_name
$users = get_users(array(
    'meta_key' => 'vcard_name',
    'meta_value' => get_query_var('vcard_name')
));

# found users (?) then get a list of ids
if( $users )
{
        # select the first user
        # This should be only one, see function nen_sanitize_vcard_name in this class
        $user_obj   = $users[0];
        $user_id    = $user_obj->ID;
}
if( $user_id )
{
        // do user stuff
}Code language: PHP (php)

Als we een ID gevonden hebben, dan is er een medewerker bekend die hoort bij de opgegeven slug. Om te achterhalen of er een vCard aan de medewerker is toegekend, vragen we de waarde van het meta-veld ‘vcard_file’ op. We hebben het zo gemaakt dat de waarde van dit veld een ID moet zijn van een mediabestand (hierover later meer). Als er een waarde in dit veld gevonden is, testen we of het bestand dat hoort bij deze ID van het type ‘vcf’ is. Als dat zo is, dan stellen we de doorstuur-url in met de url van het bestand.

// do user stuff
# there is a result on user. Does it have a vcard-file?
$vcard  = get_user_meta( $user_id , 'vcard_file' , true );
if( $vcard && wp_attachment_is( 'vcf', $vcard ) )
{
        # This is the file we need. Send vcard-url of user
        $vcard_id   = $vcard;
        $url        = wp_get_attachment_url($vcard);

        # allaow devellopers to hook on
        do_action( 'nen_vcard_download' , $user_obj );
}Code language: PHP (php)

Als laatste gaan we de bezoeker ook echt doorsturen. Als er geen url gevonden is – omdat er geen user gevonden is of omdat de user geen vCard heeft – stellen we de home-page in om naar door te sturen. Omdat we via wp_redirect gaan doorsturen naar iets nieuws, moeten we het huidige verzoek – onze vcard-url – stoppen (exit).

# no user found (?) then just send homepage.
if( ! $url ) $url = home_url();

# do redirect to the url and quit
wp_redirect( apply_filters( 'nen_vcard_url' , $url , $user_obj , $vcard_id ) );
exit;Code language: PHP (php)

Nog even de volledige functie:

add_action( 'template_redirect', 'nen_redirect_to_file' );
function nen_redirect_to_file()
{
        if( get_query_var('vcard') == '1' )
        {
                # set variables
                $user_obj   = null;
                $user_id    = null;
                $vcard_id   = null;
                $url        = null;

                # do a search for user by meta field vcard_name
                $users = get_users(array(
                    'meta_key' => 'vcard_name',
                    'meta_value' => get_query_var('vcard_name')
                ));

                # found users (?) then get a list of ids
                if( $users )
                {
                        # select the first user
                        # This should be only one, see function nen_sanitize_vcard_name in this class
                        $user_obj   = $users[0];
                        $user_id    = $user_obj->ID;
                }
                if( $user_id )
                {
                        # there is a result on . Does it have a vcard-file?
                        $vcard  = get_user_meta( $user_id , 'vcard_file' , true );
                        if( $vcard && wp_attachment_is( 'vcf', $vcard ) )
                        {
                                # This is the file we need. Send vcard-url of user
                                $vcard_id   = $vcard;
                                $url        = wp_get_attachment_url($vcard);

                                # allaow devellopers to hook on
                                do_action( 'nen_vcard_download' , $user_obj );
                        }
                }
                # no user found (?) then just send homepage.
                if( ! $url ) $url    = home_url();
                # do redirect to the url and quit
                wp_redirect( apply_filters( 'nen_vcard_url' , $url , $user_obj , $vcard_id ) );
                exit;
        }
}Code language: PHP (php)

Mooi! Nu kunnen we een bezoeker via een qr-code een vCard toesturen. Maar we willen ook per user gegevens bewerken en bestanden opslaan. Hier maken we het ons iets makkelijker. We gebruiken een plugin die we toch al bijna standaard in al onze websites installeren.

[3] Een vCard opslaan bij een medewerker/user

Voor het opslaan van extra (meta)informatie bij de medewerker, gebruiken we de plugin Advanced Custom Fields (wij gebruiken zelf de Pro-versie). Hiermee kun je aan de beheerkant formulieren maken die de informatie opslaan in de meta-tabel in de database. In de plugin die we gemaakt hebben, is een functie opgenomen die automatisch de extra velden toevoegt aan de profielpagina van de user in admin (als de AFC-plugin is geïnstalleerd). Hierbij hebben we drie velden aangemaakt:

• vcard_name (moet gelijk zijn aan de slug uit de url)
• vcard_file (opslaan van de ID van het vcard-bestand)
• vcard_qr (afbeelding van de qr-code om de vCard te kunnen downloaden)

Om er zeker van te zijn dat het veld ‘vcard_name’ geschikt is voor gebruik in een url, hebben we tevens een functie gemaakt die de waarde omzet bij het bewaren van de pagina.

Belangrijk: Advanced Custom Fields heeft ook functies om informatie op te vragen uit de database: die gebruiken wij nooit! Data opvragen doen we altijd op ‘de WordPress manier’ via get_user_meta() of get_post_meta(). Deze functies zijn altijd beschikbaar in WordPress.
Mocht de ACF-plugin namelijk uitgeschakeld raken terwijl je hun functies gebruikt, dan krijg je foutmeldingen (wit scherm). In php (programmeertaal van de server) kun je geen functies aanroepen die (op dat moment) niet bestaan.

[4] Afbeelding qr-code weergeven op de site

QR maken

Om de qr-code te kunnen weergeven, is het handigste om online een qr-afbeelding te laten maken. Gebruik deze link om een qr van het type ‘svg’ aan te maken. Deze kun je uploaden bij de user.

Let op! Er zijn onlinediensten die, voor het genereren van een qr-code, alle verzoeken via hun website laten gaan. Dus degene die scant gaat eerst naar de site van de onlinedienst en wordt daarna doorgestuurd naar de door jou ingevoerde url. Test dit door de qr met je telefoon te scannen. Op het scherm (iPhone) zie je dan de domeinnaam staan waar je als eerste naar toe gaat.

Shortcode

Voor het weergeven van de afbeelding kun je de shortcode ‘nen_user_vcard_qr’ gebruiken. Hiervoor moet je wel de waarde uit het veld vcard_name meegeven om de juiste user te selecteren. Als wordpress deze shortcode in de tekst vindt, dan laten we deze functie uitvoeren voor het weergeven van de qr-code. Naast de ‘name’ kan ook ‘id’ gebruikt worden om de user te vinden (moet wel een getal/integer zijn). Ook is de tekst boven de qr-code in te stellen door attribute ’text’ op te nemen in de shortcode. Het formaat wordt bepaald met ‘size’ in pixels. Met ‘align’ kun je de qr-code ‘left’, ‘right’, ‘center’, ‘float-left’ of ‘float-right’ plaatsen. Als je ‘link’ instelt met ’true’ dan wordt er een klikbaar element van gemaakt.

# Deze shortcode kun je plakken in je pagina-opmaak
# De attribute 'name' moet je daarna aanpassen
[nen_user_vcard_qr name="martin-van-wijngaarden" size="160" text="scan mijn vCard" align="center" link="true"]Code language: PHP (php)

Bijbehorende functie

add_shortcode( 'nen_user_vcard_qr', 'nen_shortcode_qr_image' );
function nen_shortcode_qr_image( $atts ) 
{
        extract( shortcode_atts(array(
                'id'    => null,
                'name'  => null,
                'size'  => null,
                'text'  => null,
                'align' => null,
                'link'  => null,
        ), $atts ) );
        $html           = null;
        $image_id       = null;
        $url            = null;
        $align_style    = null;
        $align_float    = null;
        if( $name )
        {
                $users = get_users(array(
                    'meta_key' => 'vcard_name',
                    'meta_value' => $name,
                ));
                if( $users )
                {
                    $id = $users[0]->ID;
                }
        }
        if( $id )
        {
                $image_id   = get_user_meta( $id , 'vcard_qr' , true );
                $vcard_name = get_user_meta( $id , 'vcard_name' , true );
                $url        = home_url( '/vcard/' . $vcard_name . '/' );
        }

        # size
        $size   = (int)$size;
        if( !$size ) $size = 200;

        # align
        if( $align && in_array( $align , ['left','center','right'] ) )
        {
                $align_style = 'text-align:' . $align . ';';
        }
        else if( $align && in_array( $align , [ 'floatleft','float left','float:left','float-left' ] ) )
        {
                $align_float = 'float:left;margin-right:12px;';
        }
        else if( $align && in_array( $align , [ 'floatright','float right','float:right','float-right' ] ) )
        {
                $align_float = 'float:right;margin-left:12px;';
        }

        # link
        if( $link && in_array( $link , [ 'true', '1' ] ) )
        {
                $link = true;
        }

        # HTML
        if( $image_id && $url )
        {
                $onclick            =  ( $link === true ? $onclick = 'window.location.href = \''. $url . '\'' : null );
                $inner_style        = 'display:inline-block;color:#999;text-align:center;font-size:75%;width:' . esc_attr($size) . 'px;';
                if( $align_float )  $inner_style .= $align_float;
                $html = '<div class="nen-vcard-qr" ' . ( $align_style ? 'style="'. esc_attr($align_style).'"' : '' ) . '>'.
                            '<div class="nen-vcard-qr-inner" style="' . esc_attr($inner_style) . '">' . 
                                ( $text ? '<span class="nen-vcard-qr-txt" style="margin-bottom: -6px; position: relative; display: block; z-index: 1; background: #fff; padding-top: 6px;">'.esc_html($text).'</span>' : '' ).
                                '<div class="nen-vcard-qr-image" '.( $onclick ? 'onclick="'.esc_attr($onclick) : '' ) .'" '.( $onclick ? 'style="cursor:pointer;"' : '' ).' >' .
                                    wp_get_attachment_image( $image_id , 'medium_large' , false, ['style'=>'width:100%'] ) .
                                '</div>' .
                            '</div>'.
                        '</div>';
        }
        return  $html;
}Code language: PHP (php)

[5] Onze plugin installeren en gebruiken

Download onderstaande zipp om dit alles te installeren als plugin. Let op! Je hebt wel de plugin Advanced Custom Fields nodig om de velden te kunnen bewerken. Ik denk dat de gratis versie al voldoende is.

Ben je handig, dan kun je ook zelf velden aanmaken bij een user. Maar je kan er ook een andere plugin voor gebruiken. Zorg dat de veldnamen voor de meta-velden overeenkomen met wat wij ontwikkeld hebben.

Vergeet niet een save te doen in de admin-omgeving bij Instellingen > permalinks na het installeren van de plugin.

Nog even de stappen

1. Download en installeer onze plugin + Advanced Custom Fields
2. Ga na activering van de plugins naar Instellingen > permalinks en klik op ‘Wijzigingen opslaan’ (zonder verder instellingen aan te passen)
3. Ga naar je profielpagina (Gebruikers > profiel) en scroll naar beneden tot de Kop ‘User vCard’
4. Stel een unieke naam in bij het veld ‘Name (slug)’ en klik op ‘Profiel updaten’ onder aan de pagina
5. Onder het veld ‘QR-image’ zie je de url staan waar je een qr-code van moet maken. Gebruik de tevens zichtbare link naar de onlinedienst om een qr-afbeelding te maken. Je krijgt van hen een zipp met een svg-bestand. Upload de svg bij het veld ‘QR-image’
6. Maak in je telefoon een contact aan met de gegevens die je wilt delen. De ingestelde afbeelding bij dit contact wordt, bij het delen van dit contact, ook meegenomen. Wij kozen voor een afgeleide van ons logo. Deel dit contact met jezelf door het naar jezelf te mailen
7. Upload dit vcf-bestand bij je profielpagina bij het veld ‘File VCard’ en klik op ‘Profiel updaten’
8. Test je vcard-download door met je telefoon de qr op je profielpagina te scannen
9. Maak een shortcode aan om de qr-afbeelding op een andere pagina zichtbaar te maken voor bezoekers.
10. Herhaal vanaf punt 4 voor elke user die een eigen vcard wil

Succes!

[!] Tip

Ben je handig met code, gebruik dan de action-hook ‘nen_vcard_download’. Deze wordt aangeroepen als er een verwijzing naar een vCard gemaakt wordt. Ik heb het zo gemaakt dat ik een e-mail krijg als iemand mijn vCard opvraagt! Leuk om te weten natuurlijk (maar ik heb er verder niets aan want ik zie niet wie het is).

do_action( 'nen_vcard_download' , $user_obj );Code language: PHP (php)