# DataFirefly Social Connect — Complete guide

> Complete installation, configuration and usage guide for DataFirefly Social Connect: social login via Google, Apple, Facebook, Microsoft, LinkedIn and X for WooCommerce, with analytics, order attribution, A/B testing and anti-fraud.

- Page: <https://www.datafirefly.com/en/documentation/datafirefly-social-connect/>
- Language: en
- Last updated: 2026-06-28
- Other languages: [fr](https://www.datafirefly.com/documentation/datafirefly-social-connect/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-social-connect/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-social-connect/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-social-connect/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-social-connect/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-social-connect/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-social-connect/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

DataFirefly Social Connect adds one-click social sign-in to your WooCommerce store via six providers (Google, Apple, Facebook, Microsoft, LinkedIn and X), a complete analytics dashboard, attribution of orders back to the originating provider, button A/B testing, an anti-fraud system and native GDPR compliance.

The plugin uses no external CDN libraries: dashboard charts are rendered with native HTML5 canvas, and the OAuth 2.0 / OpenID Connect flows are implemented directly in the module (full JWKS signature verification for Google One-Tap, on-the-fly ES256 signing for Apple, `appsecret_proof` hardening for Facebook, S256 PKCE for X).

**Requirements**: WordPress 6.2+, WooCommerce 7.0+, PHP 8.0+. The plugin declares HPOS and Cart & Checkout Blocks compatibility at activation.

## Installation

1. Download the plugin ZIP from your DataFirefly customer area.
2. In WordPress, go to _Plugins → Add New → Upload Plugin_.
3. Select the ZIP and click _Install Now_.
4. Click _Activate_. WooCommerce must be active at the time of activation, otherwise the plugin refuses to install.
5. A new _Social Connect_ menu appears in the admin sidebar, with two sub-pages: _Statistics_ and _Settings_.

On activation, two SQL tables are created: `wp_dfsc_connections` (linked accounts) and `wp_dfsc_events` (events journal for analytics). Default options are written to `dfsc_settings`.

## Provider configuration

Each provider has its own card in the _Providers_ tab of the settings. For each, the top of the card shows the **redirect URI** to copy and paste into the provider's console. This is the setting that authorises your site to receive the authentication callback.

### Google (with One-Tap)

1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create (or select) a project.
2. Under _APIs & Services → OAuth consent screen_, configure the consent screen (External type for a public store, add your domain to the authorised domains).
3. Under _Credentials → Create credentials → OAuth client ID_, choose _Web application_.
4. In _Authorized redirect URIs_, paste the URI shown in the Google card of Social Connect (form: `https://your-domain.com/?dfsc_action=callback&dfsc_provider=google`).
5. To enable Google One-Tap, also add your root domain to _Authorized JavaScript origins_.
6. Copy the _Client ID_ and _Client Secret_ into the corresponding fields of the Google card, enable the provider toggle, and tick _Show the One-Tap prompt to signed-out visitors_ if you wish.

One-Tap works with full JWKS signature verification plus `aud`, `iss` and `exp` claim checks. The validation is cryptographic, not just declarative.

### Apple (Sign in with Apple)

1. On [Apple Developer](https://developer.apple.com/) (paid account required), go to _Certificates, Identifiers & Profiles → Identifiers_.
2. Create an _App ID_ with the _Sign In with Apple_ capability enabled.
3. Then create a _Services ID_ (this is the identifier you'll use as the "Client ID" in Social Connect). Configure its Sign In with Apple: add your domain in _Domains_, and the redirect URI shown in the Apple card in _Return URLs_.
4. Create a private key (_Keys → +_), with _Sign In with Apple_ ticked, associated to your App ID. Download the `.p8` file (you can only download it once).
5. In the Apple card, fill in the _Services ID_, your _Team ID_ (visible at the top right of the portal), the _Key ID_ (shown next to the key you created), and paste the full contents of the `.p8` file into the _Private key_ field (including the `-----BEGIN PRIVATE KEY-----` lines).

Apple only returns the user's name on the very first consent, and never returns a profile picture. If the user enables "Hide My Email", an Apple relay address is provided — the plugin uses it normally. If they refuse to share an address altogether, a technical email is generated automatically.

### Facebook

1. On [Meta for Developers](https://developers.facebook.com/), create an application of type _Consumer_.
2. In the app, add the _Facebook Login → Web_ product.
3. In the Facebook Login settings, add the redirect URI shown in the Facebook card to _Valid OAuth Redirect URIs_.
4. Retrieve the _App ID_ and _App Secret_ from _Settings → Basic_ and paste them into the Facebook card.

The plugin hardens every Graph API call with `appsecret_proof` (HMAC-SHA256 of the token signed with your App Secret), per Meta's recommended practice.

### Microsoft

1. On [Microsoft Entra (formerly Azure AD)](https://entra.microsoft.com/), go to _App registrations → New registration_.
2. Name your application. For _Supported account types_, choose _Accounts in any organizational directory and personal Microsoft accounts_ if you want to accept both (uses the `common` tenant).
3. Under _Redirect URI_, choose _Web_ and paste the URI shown in the Microsoft card.
4. Once created, copy the _Application (client) ID_ into the corresponding field.
5. Under _Certificates & secrets_, create a _New client secret_, copy the value immediately (it won't be visible again) into the _Client Secret_ field.
6. Leave the _Tenant_ field on `common` to accept both personal and work/school accounts, or enter your tenant ID to restrict to one organisation.

### LinkedIn

1. On [LinkedIn Developers](https://www.linkedin.com/developers/), create an application linked to your company page.
2. In the _Products_ tab, request _Sign In with LinkedIn using OpenID Connect_. Approval is automatic.
3. In the _Auth_ tab, add the redirect URI shown in the LinkedIn card to _Authorized redirect URLs_.
4. Copy the _Client ID_ and _Client Secret_ from the _Auth_ tab into Social Connect.

### X (Twitter)

1. On the [X developer portal](https://developer.x.com/), create a project and then an application.
2. Under _User authentication settings_, enable OAuth 2.0, choose the _Confidential client_ type (recommended), and paste the redirect URI shown in the X card into _Callback URI / Redirect URL_.
3. Enter your _Website URL_ (your store homepage).
4. Copy the _Client ID_ and _Client Secret_ into Social Connect.

The X v2 API does not return an email address. The plugin automatically generates a technical address to create the matching WordPress account. If you need a real email, the user can update it from their account area afterwards.

## Placements and appearance

In the _Appearance_ tab, choose where buttons appear:

- WooCommerce **login form** (signed-out My Account page).
- WooCommerce **registration form**.
- **Checkout page**, above the form.
- **My Account dashboard**, with the list of linked accounts and the manual link buttons.

You can also insert the buttons anywhere via the shortcode:

```
[datafirefly_social_connect]
[datafirefly_social_connect context="login" heading="yes" providers="google,apple"]
[datafirefly_social_connect context="custom" redirect="https://your-site/destination/"]
```

Appearance is configurable along four axes:

- **Style**: filled (brand colours), outline (white background, coloured border), minimal (light grey background).
- **Shape**: rounded, pill, square.
- **Layout**: stacked or inline.
- **Label**: "Continue with…", "Sign in with…" or icon-only.

## Analytics dashboard

The dashboard (menu _Social Connect → Statistics_) gathers all the social-sign-in activity of your store.

### KPIs and charts

Period selector at the top right: 7, 30, 90 or 365 days. The six KPIs displayed cover:

- **Sign-ins** — total authentications over the period.
- **Registrations** — new accounts created via social sign-in.
- **Linked accounts (total)** — cumulative number of social identities linked to users.
- **Attributed orders** and **attributed revenue** — see the next section.
- **Conversion rate** — orders / sign-ins ratio.

Four charts complete the KPIs: a per-provider time-series curve, a provider-breakdown donut, a device-type donut (desktop, mobile, tablet) and a "Top countries" card fed by geolocation.

### Order attribution

Every WooCommerce order placed by a user who signed in socially is attributed to its originating provider. Attribution relies on the user meta `_dfsc_registered_via` and, as a fallback, on the user's first active social connection.

The `woocommerce_checkout_order_processed` and `woocommerce_store_api_checkout_order_processed` hooks are both listened to, covering classic checkout and blocks checkout.

## Button A/B testing

In the _Appearance_ tab, enable the _Button A/B testing_ block and configure variant B (style, shape, layout, label). From then on, each visitor is randomly assigned variant A (your base settings) or variant B (cookie `dfsc_ab`, 50/50, kept for 30 days).

An impression is counted once per visitor session (cookie `dfsc_ab_imp`), to avoid inflating the volume. Conversions are measured on sign-in, registration, linking and order events, and reported on the _A/B test_ card of the dashboard with impressions, conversions, attributed orders, per-variant rate and automatic winner designation.

For a statistically meaningful result, count at least 500 impressions per variant. Below 200, the measured differences are essentially noise.

## Anti-fraud — sign-in velocity

In the _Privacy_ tab, you can enable per-IP velocity limiting. Three thresholds are configurable:

- **Maximum attempts** — default 8.
- **Window (minutes)** — default 5.
- **Block duration (minutes)** — default 15.

Once the limit is crossed, the IP is blocked for the configured duration. A `blocked` event is journalised and appears in the recent activity. Protection applies both to classic OAuth redirects and to the Google One-Tap flow.

Independently, the plugin maintains a list of disposable email domains (Mailinator, Yopmail, 10MinuteMail, etc.) that can be blocked at registration. The list is extensible via the `dfsc_disposable_domains` filter.

## Geolocation

Enable geolocation in the _Privacy_ tab. The plugin uses the MaxMind database **already embedded by WooCommerce** — no external service is called. If you have not yet enabled geolocation on the WooCommerce side, go to _WooCommerce → Settings → General_ and enable the default geolocation option (WooCommerce will then automatically download the database).

Once enabled, the country of each sign-in is resolved and feeds the _Top countries_ card of the dashboard and the "Country" column of the CSV export.

## CSV export

The _Export CSV_ button at the top of the dashboard exports all events of the selected period. The file includes one column for each relevant field (UTC date, event, provider, context, country, device, A/B variant, user, order, total, message). A UTF-8 BOM is added at the start so Excel and LibreOffice Calc display accents correctly.

## Account linking

Three mechanisms coexist for linking a social identity to a WordPress account:

1. **Known identity** — the user has already used this provider, sign-in is immediate.
2. **Automatic linking by email** — a WordPress user already exists with the same email as the one returned by the provider. If the email is verified by the provider (and the _Email verification required_ option is enabled), the link is performed automatically.
3. **Manual linking** — from the _My Account_ dashboard, a signed-in customer can link or unlink each provider via the _Connected accounts_ panel.

## GDPR and privacy

Three IP storage modes are available in the _Privacy_ tab:

- **Hashed** (default) — HMAC-SHA256 with `wp_salt`, non-reversible.
- **Full** — plain IP (use only if your privacy policy explicitly mentions it).
- **None** — the IP is not stored at all.

The plugin declares an _exporter_ and an _eraser_ with WordPress's native GDPR system (_Tools → Export / Erase Personal Data_). When a user is deleted, their linked accounts and events are also deleted (or anonymised on erasure).

## Shortcode and advanced integration

The shortcode `[datafirefly_social_connect]` accepts the following attributes:

- `context` — `login`, `register`, `checkout` or `custom`.
- `heading` — `yes` or `no`, to display the "Quick sign-in" title above the buttons.
- `providers` — comma-separated list to limit the display (e.g. `google,apple`).
- `redirect` — absolute redirect URL after sign-in (overrides the global setting).

You can also call the rendering directly in PHP:

```
echo do_shortcode('[datafirefly_social_connect context="custom" providers="google,microsoft"]');
```

## Developer hooks and filters

- `dfsc_disposable_domains` (filter) — extends or replaces the disposable-email domain list.
- `dfsc_user_registered` (action) — fired right after a social sign-in creates a new account, with the user ID and the normalised profile.
- `dfsc_after_login` (action) — fired after every successful sign-in.
- `dfsc_welcome_subject` and `dfsc_welcome_body` (filters) — customise the welcome email subject and body.
- `dfsc_placeholder_email_domain` (filter) — changes the domain used for technical emails (Apple Hide My Email refused, X).

A read-only REST API exposes aggregated statistics at `/wp-json/datafirefly-social-connect/v1/stats?days=30` (`manage_woocommerce` capability required). Enable it in the _Privacy_ tab.

## Compatibility

- **WooCommerce HPOS** — the `custom_order_tables` compatibility is declared at activation; high-performance order storage is fully supported.
- **Checkout blocks** — the `woocommerce_store_api_checkout_order_processed` hook is listened to alongside the classic one, so order attribution works on both checkouts.
- **Polylang and WPML** — UI strings are translatable via the bundled `.pot` file (FR, EN, ES, DE, IT). Content (welcome email, etc.) is compatible with both multilingual plugins.
- **Multisite** — each network site has its own tables and options. Uninstall cleans every site.

## Uninstall

On plugin deletion from _Plugins_, the `uninstall.php` file is executed automatically. It removes:

- The `wp_dfsc_connections` and `wp_dfsc_events` tables.
- The `dfsc_settings` and `dfsc_db_version` options.
- Related transients (Google JWKS cache, Apple client-secret cache, state tokens).
- User meta (`_dfsc_provider`, `_dfsc_registered_via`, `_dfsc_avatar_id`, etc.).

Your WordPress users and WooCommerce orders are never touched. On multisite, uninstall iterates every network site.

## FAQ and troubleshooting

### The Google button shows "redirect_uri_mismatch"

The redirect URI pasted into Google Cloud Console doesn't exactly match the one shown in the Google card of Social Connect. Check that you have copied the full URI (with `https://`, the trailing slash, and the `?dfsc_action=callback&dfsc_provider=google` parameters).

### Apple returns "invalid_client"

Three possible causes: the _Services ID_ entered is not a Services ID but an App ID, the _Team ID_ is wrong, or the `.p8` private key content is incomplete (missing `-----BEGIN PRIVATE KEY-----` lines). Recheck all three and clear the Apple client-secret cache by saving the settings again.

### Facebook returns an `appsecret_proof` error

The App Secret entered is wrong or has been regenerated on Meta's side without being updated here. Go to Meta for Developers, copy the secret again, and paste it into the Facebook card.

### X / Twitter returns "invalid_request" on callback

The _Callback URI_ was not correctly entered in the X developer portal, or the app type is not _Confidential client_ while a Client Secret is mandatory. Re-check the portal.

### The dashboard is empty although I've had sign-ins

Check that the selected period actually covers your sign-ins (default 30 days). If you have just activated the plugin, wait until you have a few events before the charts come alive.

### A/B test shows 0% rates

You need a minimum of impressions and conversions before the rates become meaningful. Count a few hundred impressions per variant before interpreting results.

### Geolocation returns no country

Check that WooCommerce has actually downloaded the MaxMind database. Go to _WooCommerce → Settings → General_, enable default geolocation, and wait a few minutes. WooCommerce then keeps the database updated automatically.

### How do I force-unlink an account from the admin side?

Go to the `wp_dfsc_connections` table and delete the matching row. On the user's next sign-in via that provider, they will be treated as a new identity (and re-linked to their WordPress account by email if automatic linking is on).