Target by specific countries and/or country group

src/server/tests/epics/epicSelection.test.ts

@@ -282,6 +282,10 @@ describe('matchesCountryGroups filter', () => {
         const test = {
             ...testDefault,
             locations: [],
+            regionTargeting: {
+                targetedCountryGroups: [],
+                targetedCountryCodes: [],
+            },
         };
 
         const got = matchesCountryGroups.test(test, targetingDefault);
@@ -293,6 +297,10 @@ describe('matchesCountryGroups filter', () => {
         const test: EpicTest = {
             ...testDefault,
             locations: ['GBPCountries'],
+            regionTargeting: {
+                targetedCountryGroups: ['GBPCountries'],
+                targetedCountryCodes: [],
+            },
         };
         const targeting = {
             ...targetingDefault,
@@ -308,6 +316,10 @@ describe('matchesCountryGroups filter', () => {
         const test: EpicTest = {
             ...testDefault,
             locations: ['EURCountries'],
+            regionTargeting: {
+                targetedCountryGroups: ['EURCountries'],
+                targetedCountryCodes: [],
+            },
         };
         const targeting: EpicTargeting = {
             ...targetingDefault,
@@ -323,6 +335,86 @@ describe('matchesCountryGroups filter', () => {
         const test: EpicTest = {
             ...testDefault,
             locations: ['EURCountries'],
+            regionTargeting: {
+                targetedCountryGroups: ['EURCountries'],
+                targetedCountryCodes: [],
+            },
+        };
+        const targeting: EpicTargeting = {
+            ...targetingDefault,
+            countryCode: 'GB',
+        };
+
+        const got = matchesCountryGroups.test(test, targeting);
+
+        expect(got).toBe(false);
+    });
+
+    it('should pass if user is in country group or targeted country', () => {
+        const test: EpicTest = {
+            ...testDefault,
+            locations: ['EURCountries'],
+            regionTargeting: {
+                targetedCountryGroups: ['EURCountries'],
+                targetedCountryCodes: ['CA'],
+            },
+        };
+        const targeting: EpicTargeting = {
+            ...targetingDefault,
+            countryCode: 'DE',
+        };
+
+        const got = matchesCountryGroups.test(test, targeting);
+
+        expect(got).toBe(true);
+    });
+
+    it('should pass if user is in targeted country', () => {
+        const test: EpicTest = {
+            ...testDefault,
+            locations: [],
+            regionTargeting: {
+                targetedCountryGroups: [],
+                targetedCountryCodes: ['DE'],
+            },
+        };
+        const targeting: EpicTargeting = {
+            ...targetingDefault,
+            countryCode: 'DE',
+        };
+
+        const got = matchesCountryGroups.test(test, targeting);
+
+        expect(got).toBe(true);
+    });
+
+    it('should pass if user is in both country group or targeted country', () => {
+        const test: EpicTest = {
+            ...testDefault,
+            locations: ['EURCountries'],
+            regionTargeting: {
+                targetedCountryGroups: ['EURCountries'],
+                targetedCountryCodes: ['DE'],
+            },
+        };
+        const targeting: EpicTargeting = {
+            ...targetingDefault,
+            countryCode: 'DE',
+        };
+
+        const got = matchesCountryGroups.test(test, targeting);
+
+        expect(got).toBe(true);
+    });
+
+    it('should fail if user is not in country group or targeted country', () => {
+        const test: EpicTest = {
+            ...testDefault,
+            locations: ['EURCountries'],
+            regionTargeting: {
+                targetedCountryGroups: ['EURCountries'],
+                targetedCountryCodes: ['NZ'],
+            },
         };
         const targeting: EpicTargeting = {
             ...targetingDefault,

src/server/tests/epics/epicSelection.ts

@@ -74,7 +74,19 @@ export const hasCountryCode: Filter = {
 
 export const matchesCountryGroups: Filter = {
     id: 'matchesCountryGroups',
-    test: (test, targeting): boolean => inCountryGroups(targeting.countryCode, test.locations),
+    test: (test, targeting): boolean => {
+        const targetedRegions = test.regionTargeting
+            ? [
+                  ...(test.regionTargeting.targetedCountryGroups || []),
+                  ...(test.regionTargeting.targetedCountryCodes || []),
+              ]
+            : [];
+        return inCountryGroups(
+            targeting.countryCode,
+            test.locations, // Country groups/region
+            targetedRegions, // Individual country names
+        );
+    },
 };
 
 export const withinMaxViews = (log: EpicViewLog, now: Date = new Date()): Filter => ({

src/shared/lib/geolocation.ts

@@ -14,6 +14,13 @@ export type CountryGroupId = (typeof CountryGroupId)[number];
 
 export const countryGroupIdSchema = z.enum(CountryGroupId);
 
+export const targetedRegionsSchema = z
+    .object({
+        targetedCountryGroups: z.array(countryGroupIdSchema),
+        targetedCountryCodes: z.array(z.string()).optional(),
+    })
+    .optional();
+
 // Used to internationalise 'Support the Guardian' links
 export type SupportRegionId = 'UK' | 'US' | 'AU' | 'EU' | 'INT' | 'NZ' | 'CA';
 
@@ -560,25 +567,31 @@ export const countryCodeToCountryGroupId = (countryCode?: string): CountryGroupI
     const foundCountryGroupId = availableCountryGroupIds.find((countryGroupId) =>
         countryGroups[countryGroupId].countries.includes(countryCode ?? ''),
     );
-
     return foundCountryGroupId || 'International';
 };
 
+//inCountryGroups is a bad name now that it accepts country names seperately from country groups
 export const inCountryGroups = (
-    countryCode?: string,
+    countryCodeFromPayload?: string,
     countryGroups: CountryGroupId[] = [],
+    countryCodes: string[] = [], // Accepts individual country codes
 ): boolean => {
-    // Always True if no locations set for the test
-    if (countryGroups.length === 0) {
+    // Always True if no locations or targeted countries set for the test (so always displays epic)
+    if (countryGroups.length === 0 && countryCodes.length === 0) {
         return true;
     }
-
-    // Always False if user location unknown but test has locations set
-    if (!countryCode) {
+    // Always false if user location unknown but test has locations set (so never displays epic unless in country)
+    if (!countryCodeFromPayload) {
         return false;
     }
 
-    return countryGroups.includes(countryCodeToCountryGroupId(countryCode.toUpperCase()));
+    // Check if the country belongs to the specified country groups
+    if (countryGroups.includes(countryCodeToCountryGroupId(countryCodeFromPayload.toUpperCase()))) {
+        return true;
+    }
+
+    // Check if the country is in the targeted countries by name
+    return countryCodes.includes(countryCodeFromPayload.toUpperCase());
 };
 
 const defaultCurrencySymbol = '£';
@@ -623,3 +636,8 @@ export const addRegionIdToSupportUrl = (originalUrl: string, countryCode?: strin
 
     return originalUrl;
 };
+
+const countryNameToCodeMap: Record<string, string> = {};
+for (const [code, name] of Object.entries(countryNames)) {
+    countryNameToCodeMap[name] = code;
+}

src/shared/types/abTests/banner.ts

@@ -12,7 +12,7 @@ import {
     testSchema,
     userCohortSchema,
 } from './shared';
-import { countryGroupIdSchema } from '../../lib';
+import { countryGroupIdSchema, targetedRegionsSchema } from '../../lib';
 import { BannerTargeting, PageTracking } from '../targeting';
 import { PurchaseInfoTest } from './shared';
 import { z } from 'zod';
@@ -82,7 +82,8 @@ export interface BannerTest extends BannerTestFromTool {
 
 export const bannerTestFromToolSchema = testSchema.extend({
     userCohort: userCohortSchema,
-    locations: z.array(countryGroupIdSchema),
+    locations: z.array(countryGroupIdSchema).optional(),
+    regionTargeting: targetedRegionsSchema.optional(),
     contextTargeting: pageContextTargetingSchema,
     variants: z.array(bannerVariantFromToolSchema),
     articlesViewedSettings: articlesViewedSettingsSchema.optional(),

src/shared/types/abTests/epic.ts

@@ -1,4 +1,4 @@
-import { CountryGroupId, countryGroupIdSchema } from '../../lib';
+import { CountryGroupId, countryGroupIdSchema, targetedRegionsSchema } from '../../lib';
 import {
     articlesViewedSettingsSchema,
     testSchema,
@@ -112,7 +112,8 @@ export interface EpicTest extends EpicTestFromTool {
 export const epicTestFromToolSchema = testSchema.extend({
     name: z.string(),
     status: testStatusSchema,
-    locations: z.array(countryGroupIdSchema),
+    locations: z.array(countryGroupIdSchema).optional(), //deprecated
+    regionTargeting: targetedRegionsSchema.optional(),
     tagIds: z.array(z.string()),
     sections: z.array(z.string()),
     excludedTagIds: z.array(z.string()),

src/shared/types/abTests/header.ts

@@ -1,6 +1,6 @@
 import { testSchema, userCohortSchema, purchaseInfoTestSchema } from './shared';
 import { headerContentSchema } from '../props';
-import { countryGroupIdSchema } from '../../lib';
+import { countryGroupIdSchema, targetedRegionsSchema } from '../../lib';
 import { z } from 'zod';
 
 /**
@@ -14,7 +14,8 @@ const headerVariantFromToolSchema = z.object({
 export type HeaderVariantFromTool = z.infer<typeof headerVariantFromToolSchema>;
 
 export const headerTestFromToolSchema = testSchema.extend({
-    locations: z.array(countryGroupIdSchema),
+    locations: z.array(countryGroupIdSchema).optional(),
+    regionTargeting: targetedRegionsSchema.optional(),
     userCohort: userCohortSchema,
     purchaseInfo: purchaseInfoTestSchema.optional(),
     variants: z.array(headerVariantFromToolSchema),