fix(og): brandable static title + wider crawler UA coverage (#521)
@Rekoo-PS reported that gallery URLs sent via the WhatsApp Business API render an unbranded "PicPeak - Photo Sharing Platform" preview even though manual link sends from the WhatsApp app pick up the per-event rich preview correctly. Two root causes, two fixes: 1. WhatsApp Business and 3rd-party preview services (Twilio, LinkPreview.net, etc.) don't always crawl with the recognisable "WhatsApp/X.Y.Z" UA we matched in nginx + galleryOgService. Extend the regex (both copies) to also catch WhatsAppBot, wa-bot, LinkPreview, and Slack-ImgProxy. 2. Even with broader UA coverage, some senders cache metadata with no UA at all and fetch the static SPA shell. That shell's <title> was hard-coded to "PicPeak - Photo Sharing Platform" — embarrassingly generic for any self-hosted brand. Switch to Vite's %VITE_DEFAULT_TITLE% / %VITE_DEFAULT_DESCRIPTION% HTML substitution so self-hosters can bake their brand into the fallback at build time. Defaults stay "PicPeak" so the upstream image doesn't change behaviour for anyone. The per-event rich preview path (handleGalleryOgRequest, fired on matched crawler UAs) is unchanged — this only improves the fallback for unrecognised UAs and for the SPA-shell title that humans see in their browser tab. Adds a vite.config plugin to provide the defaults when env vars aren't set, so unsubstituted "%VITE_..." literals never reach the built HTML. Adds .env.example entries explaining the override. Tests: extend galleryOgService.shareImage.test.js with an isSocialCrawler suite that pins every documented UA (incl. the new ones) plus three browser UAs (negative) and null/empty edge cases. Verified locally: `vite build` with VITE_DEFAULT_TITLE="MyBrand" produces <title>MyBrand</title> + og:title="MyBrand"; without the env var falls back to "PicPeak". Refs: #521
This commit is contained in:
Paul Nothaft
@@ -35,6 +35,7 @@ const { getStorage } = require('../services/storage');
|
||||
const {
|
||||
buildOgMetadata,
|
||||
handleGalleryOgCover,
|
||||
isSocialCrawler,
|
||||
} = require('../services/galleryOgService');
|
||||
|
||||
// The service hits two tables in sequence:
|
||||
@@ -237,3 +238,52 @@ describe('handleGalleryOgCover — 404 unless explicitly opted in', () => {
|
||||
expect(ensureThumbnail).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
// Regression for #521 — WhatsApp Business API + 3rd-party preview
|
||||
// services use UAs that aren't "WhatsApp/X.Y.Z". If isSocialCrawler
|
||||
// misses them, those requests fall through to the static SPA shell
|
||||
// and the link preview ends up unbranded.
|
||||
describe('isSocialCrawler — extended bot coverage (#521)', () => {
|
||||
it('matches every UA the README/changelog claims to support', () => {
|
||||
// Pin the contract: each listed UA must hit the crawler path so the
|
||||
// nginx rewrite + backend OG handler stay in sync. Adding a new UA
|
||||
// here without also adding it to nginx.conf would silently regress.
|
||||
const knownBots = [
|
||||
// Main WhatsApp app
|
||||
'WhatsApp/2.23.20.0',
|
||||
// WhatsApp Business / Cloud API variants
|
||||
'WhatsAppBot/1.0',
|
||||
'wa-bot/2.0',
|
||||
// Other messaging app crawlers
|
||||
'facebookexternalhit/1.1',
|
||||
'Twitterbot/1.0',
|
||||
'Slackbot-LinkExpanding 1.0',
|
||||
'TelegramBot (like TwitterBot)',
|
||||
// 3rd-party preview services used by business-messaging stacks
|
||||
'LinkPreview/1.0',
|
||||
'Slack-ImgProxy/1.0',
|
||||
];
|
||||
for (const ua of knownBots) {
|
||||
expect(isSocialCrawler(ua)).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
it('does not match a regular browser UA', () => {
|
||||
const browsers = [
|
||||
'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36',
|
||||
'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15',
|
||||
// Browser UA that happens to contain "Mobile" — guard against an
|
||||
// over-broad regex landing on it.
|
||||
'Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 Chrome/120.0 Mobile Safari/537.36',
|
||||
];
|
||||
for (const ua of browsers) {
|
||||
expect(isSocialCrawler(ua)).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it('returns false for null/empty/undefined UAs', () => {
|
||||
expect(isSocialCrawler(null)).toBe(false);
|
||||
expect(isSocialCrawler(undefined)).toBe(false);
|
||||
expect(isSocialCrawler('')).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -7,7 +7,12 @@ const SOCIAL_CRAWLER_PATTERNS = [
|
||||
/facebookexternalhit/i,
|
||||
/facebot/i,
|
||||
/Twitterbot/i,
|
||||
// WhatsApp's main app crawler is "WhatsApp/X.Y.Z"; the Business
|
||||
// API and some Cloud API senders use "WhatsAppBot" or "wa-bot/" —
|
||||
// detect both so API-driven sends get the rich preview too (#521).
|
||||
/WhatsApp/i,
|
||||
/WhatsAppBot/i,
|
||||
/wa-bot/i,
|
||||
/Slackbot/i,
|
||||
/TelegramBot/i,
|
||||
/SkypeUriPreview/i,
|
||||
@@ -24,7 +29,12 @@ const SOCIAL_CRAWLER_PATTERNS = [
|
||||
/Mastodon/i,
|
||||
/Bluesky/i,
|
||||
/OpenGraph/i,
|
||||
/opengraph/i
|
||||
/opengraph/i,
|
||||
// Generic preview/scrape services commonly used in business
|
||||
// messaging stacks (Twilio, LinkPreview.net, etc.). Match the
|
||||
// canonical lowercase substring; the /i flag handles case.
|
||||
/LinkPreview/i,
|
||||
/Slack-ImgProxy/i
|
||||
];
|
||||
|
||||
function isSocialCrawler(userAgent) {
|
||||
|
||||
@@ -1,3 +1,19 @@
|
||||
# Static HTML fallback for social-link previews (#521).
|
||||
#
|
||||
# Most link previews (WhatsApp, Facebook, Slack, etc.) hit the backend's
|
||||
# per-event OG endpoint and get the actual event name + branding. Some
|
||||
# third-party preview services and the WhatsApp Business API cache
|
||||
# metadata with a non-crawler User-Agent and end up reading these static
|
||||
# values instead. Set these to your brand so that fallback isn't generic
|
||||
# "PicPeak - Photo Sharing Platform".
|
||||
#
|
||||
# These are baked into index.html at build time, so they take effect on
|
||||
# the next `npm run build` / docker build. Live admin Branding settings
|
||||
# do NOT propagate here — for that, use the per-event OG endpoint, which
|
||||
# always serves the live branded preview.
|
||||
VITE_DEFAULT_TITLE=PicPeak
|
||||
VITE_DEFAULT_DESCRIPTION=Photo gallery shared with PicPeak.
|
||||
|
||||
# Backend API URL
|
||||
# For local development with Docker:
|
||||
VITE_API_URL=http://localhost:3001/api
|
||||
|
||||
@@ -1,6 +1,12 @@
|
||||
# Production Environment Configuration
|
||||
# When running behind a reverse proxy like Traefik, use relative URLs
|
||||
|
||||
# Static HTML fallback for social-link previews (#521).
|
||||
# Override these with your brand so previews that hit the static
|
||||
# index.html (vs the per-event OG endpoint) aren't generic.
|
||||
VITE_DEFAULT_TITLE=PicPeak
|
||||
VITE_DEFAULT_DESCRIPTION=Photo gallery shared with PicPeak.
|
||||
|
||||
# Backend API URL
|
||||
# For production behind reverse proxy, use relative URL:
|
||||
VITE_API_URL=/api
|
||||
|
||||
+27
-1
@@ -4,7 +4,33 @@
|
||||
<meta charset="UTF-8" />
|
||||
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
|
||||
<title>PicPeak - Photo Sharing Platform</title>
|
||||
<!--
|
||||
Static fallback title + Open Graph defaults (#521).
|
||||
|
||||
The runtime SPA updates these once React loads, and social-crawler
|
||||
User-Agents hitting /gallery/<slug> get a per-event rich preview
|
||||
served by backend's galleryOgService instead of this static shell.
|
||||
|
||||
But the third path — link previews fetched by WhatsApp Business
|
||||
API, Twilio, LinkPreview, or any service that caches metadata
|
||||
with a non-crawler UA — gets *this* HTML as-is. Defaulting the
|
||||
title to "PicPeak - Photo Sharing Platform" left every such
|
||||
preview looking unbranded for self-hosted installs.
|
||||
|
||||
Self-hosters set VITE_DEFAULT_TITLE / VITE_DEFAULT_DESCRIPTION
|
||||
at build time (see .env.example) to bake their brand into this
|
||||
fallback. Default values keep the upstream-image behaviour for
|
||||
anyone who doesn't override them.
|
||||
-->
|
||||
<title>%VITE_DEFAULT_TITLE%</title>
|
||||
<meta name="description" content="%VITE_DEFAULT_DESCRIPTION%" />
|
||||
<meta property="og:type" content="website" />
|
||||
<meta property="og:site_name" content="%VITE_DEFAULT_TITLE%" />
|
||||
<meta property="og:title" content="%VITE_DEFAULT_TITLE%" />
|
||||
<meta property="og:description" content="%VITE_DEFAULT_DESCRIPTION%" />
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:title" content="%VITE_DEFAULT_TITLE%" />
|
||||
<meta name="twitter:description" content="%VITE_DEFAULT_DESCRIPTION%" />
|
||||
|
||||
<!-- Pre-React theme bootstrap (#358).
|
||||
The browser may paint the very first frame before our inline
|
||||
|
||||
+5
-1
@@ -184,7 +184,11 @@ server {
|
||||
# meta tags never reach them. Route those UAs to backend's /og handler
|
||||
# via internal rewrite; humans fall through to the SPA via try_files.
|
||||
location ~ ^/gallery/(?<gallery_slug>[A-Za-z0-9_-]+)(?:/[^/]+)?/?$ {
|
||||
if ($http_user_agent ~* "(facebookexternalhit|facebot|Twitterbot|WhatsApp|Slackbot|TelegramBot|SkypeUriPreview|Discordbot|LinkedInBot|Pinterest|vkShare|redditbot|Embedly|iframely|Snapchat|Applebot|Mastodon|Bluesky|OpenGraph)") {
|
||||
# Keep this list in sync with SOCIAL_CRAWLER_PATTERNS in
|
||||
# backend/src/services/galleryOgService.js. WhatsAppBot / wa-bot
|
||||
# and LinkPreview / Slack-ImgProxy added in #521 to catch
|
||||
# business-API preview fetchers that aren't the main WhatsApp app.
|
||||
if ($http_user_agent ~* "(facebookexternalhit|facebot|Twitterbot|WhatsApp|WhatsAppBot|wa-bot|Slackbot|Slack-ImgProxy|TelegramBot|SkypeUriPreview|Discordbot|LinkedInBot|Pinterest|vkShare|redditbot|Embedly|iframely|Snapchat|Applebot|Mastodon|Bluesky|OpenGraph|LinkPreview)") {
|
||||
rewrite ^ /og/gallery/$gallery_slug last;
|
||||
}
|
||||
try_files $uri $uri/ /index.html;
|
||||
|
||||
+23
-2
@@ -1,13 +1,34 @@
|
||||
/// <reference types="vitest" />
|
||||
// @ts-nocheck
|
||||
|
||||
import { defineConfig } from 'vite'
|
||||
import { defineConfig, loadEnv } from 'vite'
|
||||
import react from '@vitejs/plugin-react'
|
||||
import type { UserConfig as VitestUserConfig } from 'vitest/config'
|
||||
|
||||
// Inject defaults for the %VITE_DEFAULT_TITLE% / %VITE_DEFAULT_DESCRIPTION%
|
||||
// placeholders in index.html when the env vars aren't set (#521). Without
|
||||
// this, Vite would leave the literal "%VITE_DEFAULT_TITLE%" string in the
|
||||
// built HTML, breaking the link-preview fallback we're trying to create.
|
||||
//
|
||||
// Self-hosters override by exporting the env vars at build time
|
||||
// (typical Docker build pattern: --build-arg VITE_DEFAULT_TITLE="My Brand").
|
||||
function htmlTitleDefaults(mode: string) {
|
||||
const env = loadEnv(mode, process.cwd(), 'VITE_')
|
||||
const title = env.VITE_DEFAULT_TITLE || 'PicPeak'
|
||||
const description = env.VITE_DEFAULT_DESCRIPTION || 'Photo gallery shared with PicPeak.'
|
||||
return {
|
||||
name: 'html-title-defaults',
|
||||
transformIndexHtml(html: string) {
|
||||
return html
|
||||
.replaceAll('%VITE_DEFAULT_TITLE%', title)
|
||||
.replaceAll('%VITE_DEFAULT_DESCRIPTION%', description)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// https://vite.dev/config/
|
||||
const config: VitestUserConfig = {
|
||||
plugins: [react()],
|
||||
plugins: [react(), htmlTitleDefaults(process.env.NODE_ENV || 'production')],
|
||||
build: {
|
||||
rollupOptions: {
|
||||
output: {
|
||||
|
||||
Reference in New Issue
Block a user