New Module: LiveIntent Omni-channel Identity

extra/bundle/pom.xml

@@ -55,6 +55,11 @@
             <artifactId>pb-request-correction</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.prebid.server.hooks.modules</groupId>
+            <artifactId>live-intent-omni-channel-identity</artifactId>
+            <version>${project.version}</version>
+        </dependency>
     </dependencies>
 
     <build>

extra/modules/live-intent-omni-channel-identity/README.md

@@ -0,0 +1,46 @@
+# Overview
+
+This module enriches bid requests with user EIDs.
+
+The user EIDs to be enriched are configured per partner as part of the LiveIntent HIRO onboarding process. As part of this onboarding process, partners will also be provided with the `identity-resolution-endpoint` URL as well as with the `auth-token`.
+
+`treatment-rate` is a value between 0.0 and 1.0 (including 0.0 and 1.0) and defines the percentage of requests for which identity enrichment should be performed. This value can be freely picked. We recommend a value between 0.9 and 0.95
+
+## Configuration
+
+To start using the LiveIntent Omni Channel Identity module you have to enable it and add configuration:
+
+```yaml
+hooks:
+  liveintent-omni-channel-identity:
+    enabled: true
+  host-execution-plan: >
+    {
+      "endpoints": {
+        "/openrtb2/auction": {
+          "stages": {
+            "processed-auction-request": {
+              "groups": [
+                {
+                  "timeout": 100,
+                  "hook-sequence": [
+                    {
+                      "module-code": "liveintent-omni-channel-identity",
+                      "hook-impl-code": "liveintent-omni-channel-identity-enrichment-hook"
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  modules:
+    liveintent-omni-channel-identity:
+      request-timeout-ms: 2000
+      identity-resolution-endpoint: "https://liveintent.com/idx"
+      auth-token: "secret-token"
+      treatment-rate: 0.9
+```
+

extra/modules/live-intent-omni-channel-identity/pom.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.prebid.server.hooks.modules</groupId>
+        <artifactId>all-modules</artifactId>
+        <version>3.26.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>live-intent-omni-channel-identity</artifactId>
+
+    <name>live-intent-omni-channel-identity</name>
+    <description>LiveIntent Omni-Channel Identity</description>
+
+    <dependencies>
+    </dependencies>
+</project>

extra/modules/live-intent-omni-channel-identity/src/main/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/config/LiveIntentOmniChannelIdentityConfiguration.java

@@ -0,0 +1,36 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.config;
+
+import org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.config.ModuleConfig;
+import org.prebid.server.hooks.modules.liveintent.omni.channel.identity.v1.LiveIntentOmniChannelIdentityModule;
+import org.prebid.server.hooks.modules.liveintent.omni.channel.identity.v1.hooks.LiveIntentOmniChannelIdentityProcessedAuctionRequestHook;
+import org.prebid.server.hooks.v1.Hook;
+import org.prebid.server.hooks.v1.InvocationContext;
+import org.prebid.server.hooks.v1.Module;
+import org.prebid.server.json.JacksonMapper;
+import org.prebid.server.vertx.httpclient.HttpClient;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.util.Set;
+
+@Configuration
+@ConditionalOnProperty(
+        prefix = "hooks." + LiveIntentOmniChannelIdentityModule.CODE, name = "enabled", havingValue = "true"
+)
+public class LiveIntentOmniChannelIdentityConfiguration {
+
+    @Bean
+    @ConfigurationProperties(prefix = "hooks.modules." + LiveIntentOmniChannelIdentityModule.CODE)
+    ModuleConfig moduleConfig() {
+        return new ModuleConfig();
+    }
+
+    @Bean
+    Module liveIntentOmniChannelIdentityModule(ModuleConfig config, JacksonMapper mapper, HttpClient httpClient) {
+        final Set<? extends Hook<?, ? extends InvocationContext>> hooks = Set.of(
+                new LiveIntentOmniChannelIdentityProcessedAuctionRequestHook(config, mapper, httpClient));
+        return new LiveIntentOmniChannelIdentityModule(hooks);
+    }
+}

extra/modules/live-intent-omni-channel-identity/src/main/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/model/IdResResponse.java

@@ -0,0 +1,18 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.iab.openrtb.request.Eid;
+import lombok.Builder;
+import lombok.Data;
+import lombok.extern.jackson.Jacksonized;
+
+import java.util.List;
+
+@Builder
+@Data
+@Jacksonized
+public class IdResResponse {
+
+    @JsonProperty("eids")
+    List<Eid> eids;
+}

extra/modules/live-intent-omni-channel-identity/src/main/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/model/config/ModuleConfig.java

@@ -0,0 +1,12 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.config;
+
+import lombok.Data;
+
+@Data
+public final class ModuleConfig {
+
+    long requestTimeoutMs;
+    String identityResolutionEndpoint;
+    String authToken;
+    float treatmentRate;
+}

extra/modules/live-intent-omni-channel-identity/src/main/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/v1/LiveIntentOmniChannelIdentityModule.java

@@ -0,0 +1,23 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.v1;
+
+import org.prebid.server.hooks.v1.Hook;
+import org.prebid.server.hooks.v1.InvocationContext;
+import org.prebid.server.hooks.v1.Module;
+
+import java.util.Collection;
+
+public record LiveIntentOmniChannelIdentityModule(
+        Collection<? extends Hook<?, ? extends InvocationContext>> hooks) implements Module {
+
+    public static final String CODE = "liveintent-omni-channel-identity";
+
+    @Override
+    public String code() {
+        return CODE;
+    }
+
+    @Override
+    public Collection<? extends Hook<?, ? extends InvocationContext>> hooks() {
+        return hooks;
+    }
+}

extra/modules/live-intent-omni-channel-identity/src/main/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/v1/hooks/LiveIntentOmniChannelIdentityProcessedAuctionRequestHook.java

@@ -0,0 +1,126 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.v1.hooks;
+
+import com.iab.openrtb.request.BidRequest;
+import com.iab.openrtb.request.Eid;
+import com.iab.openrtb.request.User;
+import io.vertx.core.Future;
+import io.vertx.core.MultiMap;
+import org.prebid.server.hooks.execution.v1.InvocationResultImpl;
+import org.prebid.server.hooks.execution.v1.auction.AuctionRequestPayloadImpl;
+import org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.IdResResponse;
+import org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.config.ModuleConfig;
+import org.prebid.server.hooks.v1.InvocationAction;
+import org.prebid.server.hooks.v1.InvocationResult;
+import org.prebid.server.hooks.v1.InvocationStatus;
+import org.prebid.server.hooks.v1.auction.AuctionInvocationContext;
+import org.prebid.server.hooks.v1.auction.AuctionRequestPayload;
+import org.prebid.server.hooks.v1.auction.ProcessedAuctionRequestHook;
+import org.prebid.server.json.JacksonMapper;
+import org.prebid.server.log.Logger;
+import org.prebid.server.log.LoggerFactory;
+import org.prebid.server.util.HttpUtil;
+import org.prebid.server.vertx.httpclient.HttpClient;
+import org.prebid.server.vertx.httpclient.model.HttpClientResponse;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Random;
+
+public class LiveIntentOmniChannelIdentityProcessedAuctionRequestHook implements ProcessedAuctionRequestHook {
+
+    private static final Logger logger =
+            LoggerFactory.getLogger(LiveIntentOmniChannelIdentityProcessedAuctionRequestHook.class);
+    private static final String CODE = "liveintent-omni-channel-identity-enrichment-hook";
+
+    private final ModuleConfig config;
+    private final JacksonMapper mapper;
+    private final HttpClient httpClient;
+    private final Random random;
+
+    public LiveIntentOmniChannelIdentityProcessedAuctionRequestHook(
+            ModuleConfig config,
+            JacksonMapper mapper,
+            HttpClient httpClient) {
+
+        this(config, mapper, httpClient, new Random());
+    }
+
+    public LiveIntentOmniChannelIdentityProcessedAuctionRequestHook(
+            ModuleConfig config,
+            JacksonMapper mapper,
+            HttpClient httpClient,
+            Random random) {
+
+        this.config = Objects.requireNonNull(config);
+        this.mapper = Objects.requireNonNull(mapper);
+        this.httpClient = Objects.requireNonNull(httpClient);
+        this.random = random;
+    }
+
+    @Override
+    public Future<InvocationResult<AuctionRequestPayload>> call(
+            AuctionRequestPayload auctionRequestPayload,
+            AuctionInvocationContext invocationContext
+    ) {
+        if (random.nextFloat() < config.getTreatmentRate()) {
+            final Future<InvocationResult<AuctionRequestPayload>> update = requestEnrichment(auctionRequestPayload)
+                    .map(resolutionResult ->
+                            InvocationResultImpl.<AuctionRequestPayload>builder()
+                                    .status(InvocationStatus.success)
+                                    .action(InvocationAction.update)
+                                    .payloadUpdate(requestPayload -> updatedPayload(requestPayload, resolutionResult))
+                                    .build()
+                    );
+
+            return update.onFailure(throwable -> logger.error("Failed enrichment:", throwable));
+        } else {
+            return Future.succeededFuture(
+                    InvocationResultImpl.<AuctionRequestPayload>builder()
+                            .status(InvocationStatus.success)
+                            .action(InvocationAction.no_action)
+                            .build());
+        }
+    }
+
+    @Override
+    public String code() {
+        return CODE;
+    }
+
+    private AuctionRequestPayload updatedPayload(AuctionRequestPayload requestPayload, IdResResponse idResResponse) {
+        final BidRequest bidRequest = Optional.ofNullable(
+                requestPayload.bidRequest()).orElse(BidRequest.builder().build());
+        final User user = Optional.ofNullable(bidRequest.getUser()).orElse(User.builder().build());
+
+        final List<Eid> allEids = new ArrayList<>();
+        allEids.addAll(Optional.ofNullable(user.getEids()).orElse(Collections.emptyList()));
+        allEids.addAll(idResResponse.getEids());
+
+        final User updatedUser = user.toBuilder().eids(allEids).build();
+        final BidRequest updatedBidRequest = requestPayload.bidRequest().toBuilder().user(updatedUser).build();
+
+        return AuctionRequestPayloadImpl.of(updatedBidRequest);
+    }
+
+    private Future<IdResResponse> requestEnrichment(AuctionRequestPayload auctionRequestPayload) {
+        final String bidRequestJson = mapper.encodeToString(auctionRequestPayload.bidRequest());
+        return httpClient.post(
+                        config.getIdentityResolutionEndpoint(),
+                        headers(),
+                        bidRequestJson,
+                        config.getRequestTimeoutMs())
+                .map(this::processResponse);
+    }
+
+    private IdResResponse processResponse(HttpClientResponse response) {
+        return mapper.decodeValue(response.getBody(), IdResResponse.class);
+    }
+
+    private MultiMap headers() {
+        return MultiMap.caseInsensitiveMultiMap()
+                .add(HttpUtil.AUTHORIZATION_HEADER, "Bearer " + config.getAuthToken());
+    }
+}

extra/modules/live-intent-omni-channel-identity/src/test/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/model/config/IdResResponseTest.java

@@ -0,0 +1,35 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.config;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.IdResResponse;
+import org.prebid.server.json.JacksonMapper;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class IdResResponseTest {
+
+    private JacksonMapper jacksonMapper;
+
+    @BeforeEach
+    public void setUp() {
+        final ObjectMapper mapper = new ObjectMapper();
+        jacksonMapper = new JacksonMapper(mapper);
+    }
+
+    @Test
+    public void shouldDecodeFromString() {
+        // given
+        final IdResResponse result = jacksonMapper.decodeValue(
+                "{\"eids\": [ { \"source\": \"liveintent.com\", "
+                        + "\"uids\": [ { \"atype\": 3, \"id\" : \"some_id\" } ] } ] }",
+                IdResResponse.class);
+        // when and then
+        assertThat(result.getEids()).hasSize(1);
+        assertThat(result.getEids().getFirst().getSource()).isEqualTo("liveintent.com");
+        assertThat(result.getEids().getFirst().getUids()).hasSize(1);
+        assertThat(result.getEids().getFirst().getUids().getFirst().getAtype()).isEqualTo(3);
+        assertThat(result.getEids().getFirst().getUids().getFirst().getId()).isEqualTo("some_id");
+    }
+}

extra/modules/live-intent-omni-channel-identity/src/test/java/org/prebid/server/hooks/modules/liveintent/omni/channel/identity/model/config/ModuleConfigTest.java

@@ -0,0 +1,33 @@
+package org.prebid.server.hooks.modules.liveintent.omni.channel.identity.model.config;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class ModuleConfigTest {
+
+    @Test
+    public void shouldReturnRequestTimeoutMs() {
+        final ModuleConfig moduleConfig = new ModuleConfig();
+        moduleConfig.setRequestTimeoutMs(5);
+        assertThat(moduleConfig.getRequestTimeoutMs()).isEqualTo(5);
+    }
+
+    @Test
+    public void shouldReturnIdentityResolutionEndpoint() {
+        // given
+        final ModuleConfig moduleConfig = new ModuleConfig();
+        moduleConfig.setIdentityResolutionEndpoint("https://test.com/idres");
+        // when and then
+        assertThat(moduleConfig.getIdentityResolutionEndpoint()).isEqualTo("https://test.com/idres");
+    }
+
+    @Test
+    public void shouldReturnAuthToken() {
+        // given
+        final ModuleConfig moduleConfig = new ModuleConfig();
+        moduleConfig.setAuthToken("secret_token");
+        // when and then
+        assertThat(moduleConfig.getAuthToken()).isEqualTo("secret_token");
+    }
+}