# GoodID WP Connect

Using the **GoodID service** allows your website visitors and customers to log in or register without the need
to fill registration forms and remember usernames and passwords. Additionally for GoodID users you can easily provide digital passes into their GoodID Wallet that you can use for your events.
Any user data that is required by WordPress or WooCommerce is supported by GoodID.
WooCommerce is supported and **currently needed** by the GoodID plugin.

## How GoodID works?

**GoodID provides a secure and fast way to register and login to online sites**, bypassing usernames and passwords.
It works by establishing a secure connection between your phone and your browser,
creating a secret token that is virtually unhackable.

**When you want to register to a new site as a user**, you receive a request into your GoodID listing all the fields that the site wants you to share. at this point your are able to decide what information you wish to share and GoodID takes care
of the process, providing fast registration and login. 
When you want to log in to any sites, you receive a message on your phone, asking you to quickly verify that you are indeed trying to access that site.
With one tap on your phone, you are logged in, safe in the knowledge that no one can log in as you.

**When you as the administrator wants to add a digital pass to the user**, you just need to set up the event details (event name, date and address) to the specific product and a unique pass will appear on your user's phone immediately after the order was completed.

For more information please visit www.goodid.net 

#### Why should I use GoodID?

* No more passwords to remember
* Secure surfing
* Streamlined registration
* Your data in your hand
* Protection against phishing attacks
* One app for all your needs
* Digital passes for your events

#### What are the benefits of GoodID

* Build trust with your users
* Protect your users from phishing attacks
* Acquire new users from the GoodID providers' desktop
* Streamlined registration and login
* Verify that your users are who they say they are
* Easy to integrate

## Setting up

### Plugin pre-requisite

To enable the **GoodID WP Connect** plugin you must sign up to become a Client on GoodID.
To signing up please contact us in email support@goodid.net .

### Required settings

Once you become a GoodID Client you receive your identifier ( *client_id* ) and secret (*client_secret*). Into the GoodID menu on the administrator interface you need to set these along with the data (*claims*) that you need from a user for registration and even the mapping rules between the received data and Wordpress and Woocommerce. Additionally you need to set whether you want the GoodID plugin to register new user into *wp_users* table or your want to store users data only in session.

### Display GoodID button

#### My account, Checkout and Login pages

On the admin interface in the GoodID menu you can set whether you want to display GoodID button on these pages and even set if you want to automatically hide the type of default login or not.

In these cases we always display GoodID login button in default size and we always using the default claim set.

#### Shortcode

You can add an extra **Sign in with GoodID** button to any place on your website with this shortcode: **[goodid_login_button]**. The button will only be visible if the user is not logged in already.

When you want to display GoodID login button by using short code you have some additional options to set. These are:
*  ```size``` : The supported values are: ```small``` , ```default```, ```large```
*  ```claimset```: You can set the ID of the claimset that you want to use.

For example:
```[goodid_login_button size="large"]```

#### Event settings

To enable the digital pass functionality on your site please set the **Event ticket template ID** in GoodID menu on administrator interface. You can receive one from us on support@goodid.net 
After that you are able to enable or disable event pass functionality and set event data to specific product on product setting page.

#### What kind of data can I request from the user with GoodID and how?

In the GoodID tab of your WordPress admin interface you have two settings, that define the requested data and its storage.

The **Claims** setting defines what data do you ask.
Please always include ```"email": {"essential": true}, "email_verified": {"value": true}``` as requesting a verified e-mail address is necessary for the wordpress plugin.
The value of the essential parameter defines whether filling the claim is required or optional.

The following is a short example:

```json
{
    "id_token": {},
    "userinfo": {
        "email": {
            "essential": true
        },
        "email_verified": {
            "value": true
        },
        "family_name": {
            "essential": false
        },
        "middle_name": {
            "essential": false
        },
        "given_name": {
            "essential": false
        },
        "billto.company_name": {
            "essential": false
        }
    }
}
```

A default claimset is included in the plugin as default-claims.json.

The list of all supported claims can be found here: http://goodid.s3.amazonaws.com/manual/3.+GoodID+Scopes+and+claims.pdf

The **Mapping** setting defines the mapping between the requested claims and the WordPress or WooCommerce fields.
The **user_email** field must not be mapped in the mapping, because it is automatically handled by the plugin.

This is a short example:

```json
{
    "wordpress": {
        "first_name": [
            "concatenate",
            "middle_name",
            "given_name"
        ],
        "last_name": "family_name"
    },
    "woocommerce": {
        "billing_company_name": "billto.company_name"
    }
}
```

The mapping is divided into groups for clarity.
If you have any other plugin which handles custom data about the user, you can also map that data from GoodID in a new group. You can name a group anything.

A single mapping item uses one of the following formats:

```
1.
"wordpress_field_name": "goodid_claim_name"

2.
"wordpress_field_name": [
    "concatenate",
    "goodid_claim_name1",
    "goodid_claim_name2",
    ...
]

3.
"shipping_state": [
    "get_wc_region",
    "address.country_code_iso_2",
    "address.region"
]

4.
"billing_state": [
    "get_wc_region",
    "billto.address.country_code_iso_2",
    "billto.address.region"
]
```

The first version is the easiest, it means mapping a single GoodID claim to a single WordPress (or any plugin) field.
With more mapping items, you can map a single GoodID claim to any number of WordPress fields, but a WordPress field must have only one mapping. If a GoodID claim is optional and not filled by the user, mappings which refer to it have no effect.

The second version maps the concatenation of any number of GoodID claims to a WordPress field. The claims that are filled by the user are separated by a space. If no claim is filled by the user, then the mapping has no effect.

The 3rd and 4th version describes a mapping between GoodID address data and WooCommerce state. The special syntax is needed because WooCommerce uses a special state code which we have to calculate from a country code and a region.

A default mapping is included in the plugin as default-mapping.json.

## Functions

#### How to get data of session stored users?

```php
$goodidUser = new GoodID_WP_User(new GoodID_WP_Settings());
$claims = $goodidUser->getClaims();
$mappedBillingFirstName = $goodidUser->getDataByMapping(null, 'billing_first_name');
```

#### How to "logging out" a session stored user?

```php
$goodidUser = new GoodID_WP_User(new GoodID_WP_Settings());
$goodidUser->logout();
```

#### How to know who has downloaded the event pass?

```php
$goodidPassData = new GoodID_WP_Pass_Data(new GoodID_WP_Settings());
$entitledUsers = $goodidPassData->get(11);

if ($entitledUsers) {
    foreach ($entitledUsers->get() as $entitledUser) {
        if ($entitledUser->hasDownloaded()) {
            // Downloaded the pass
        }
    }
}
```

#### How to know who visited the event?

```php
$goodidPassData = new GoodID_WP_Pass_Data(new GoodID_WP_Settings());
$entitledUsers = $goodidPassData->get(11);

if ($entitledUsers) {
    foreach ($entitledUsers->get() as $entitledUser) {
        if ($entitledUser->hasUsed()) {
            // The user visited the event
        }
    }
}
```

#### How to set the event data automatically?

```php
$goodidProductSettingHelper = new GoodID_WP_ProductSettingHelper(new GoodID_WP_Settings());
$goodidProductSettingHelper->saveEventSettings(...);
```

#### How to update who is entitled for a specific pass?

```php

// if the user is not registered
$entitledUsers = GoodID_WP_Pass_EntitledUsers::create($item->get_id());

if ($entitledUsers) {
    foreach ($entitledUsers->get() as $key => $entitledUser) {
        $entitledUser->reAssign('John Doe', 'john.doe@example.com');
    }
}

wc_update_order_item_meta($item->get_id(), GoodID_WP_Pass_Generator::ORDER_ITEM_META_NAME, $entitledUsers->toArray());

// or if the user is registered
$entitledUsers = GoodID_WP_Pass_EntitledUsers::create($item->get_id());

if ($entitledUsers) {
    foreach ($entitledUsers->get() as $key => $entitledUser) {
        $entitledUser->reAssign($newUserId);
    }
}

wc_update_order_item_meta($item->get_id(), GoodID_WP_Pass_Generator::ORDER_ITEM_META_NAME, $entitledUsers->toArray());

```

#### How to know whether the event settings for a specific product is set or not?

```php

$goodidProductSettingHelper = new GoodID_WP_ProductSettingHelper(new GoodID_WP_Settings());
$goodidProductSettingHelper->hasEventSettingSetForProduct($productId);

```

## Want to know more?

If you want to know more, please visit
https://goodid.net

## Note
    Note: The github repository is for development only.
    The official release is distributed through WordPress website.