Skip to main content

Java Business SDK for Conversions API v3

Introduction

The Business SDK for CAPI v3 will be designed to streamline the setup and integration process for partners using Snapchat's Conversion API V3. By offering easy authentication, simplified API interactions, and comprehensive documentation, it aims to significantly reduce the effort required for sending events.

Requirements

The CAPI Business SDK will be available on maven central. (For pilot users, please contact us for the pre-build jar before the official release).
Please add the code snippet below to import the dependencies.

Maven

<dependency>
<groupId>com.snap.business.sdk.v3</groupId>
<artifactId>snap-capi</artifactId>
<version>1.1.5</version>
<scope>compile</scope>
</dependency>

Gradle

dependencies {
implementation "com.snap.business.sdk.v3:snap-capi:1.1.5"
}

Minimum versions

  • Java >= 8

Using the SDK

Authentication

To use the Conversions API, you need to use the access token for auth.
How to generate the token.

Building CapiEvent

  • Please check with the section Conversion Parameters and provide as much information as possible when creating the CapiEvent object.
  • Every CAPI attribute has a corresponding setter in the CapiEvent class following the camelcase naming convention.
  • At least one of the following parameters is required in order to successfully send events via the Conversions API. When possible, we recommend passing all of the below parameters to improve performance:
    • em (hashed email)
    • ph (hashed phone number)
    • client_ip_address & client_user_agent
    • madid (Mobile Advertising ID) for app events only
  • For the “hashing required” user data parameters (e.g. em), our API would accept the hashed value only (see Data Hygiene).
  • We highly recommend passing cookie1 sc_cookie1, if available, as this will increase your match rate. You can access a 1st party cookie by looking at the _scid value under your domain if you are using the Pixel SDK.

Send Events

  • Conversion events can be sent individually via sendEvent(String assetId, CapiEvent capiEvent).
  • Conversion events can be reported in batch using sendEventsBatch(String assetId, List<CapiEvent> capiEvents) if they are buffered in your application.
  • If you prefer to send the events asynchronous, please use sendEventAsync(String assetId, CapiEvent capiEvent) and sendEventsBatchAsync(String assetId, List<CapiEvent> capiEvents) instead. The response is logged by a default callback (under debugging mode)

Validation, Logs, and Stats

  • Conversion events can be sent for testing and validation via the sendValidateEvent(String assetId, CapiEvent capiEvent) and sendValidateEventsBatch(String assetId, List<CapiEvent> capiEvents).
  • Conversion API also provides a logging endpoint. Use getValidateEventLogs(String assetId) to get the logs. It returns a summary of tests sent within the past day.
  • Use getValidateEventStats(String assetId) to get basic stats and summary of the test events sent.
  • Please check example/SendTestEvents.java for more information.

Debugging Mode

  • When debugging mode is turned on, we will log the events, api call response and exceptions using SLF4J logger.
    • By default, SLF4J logger will bind to java.util.logging (JUL) and log to console.
    • SLF4J logger can detect the logging framework from your class path and bind a logging framework at deployment time. It can support various logging frameworks (e.g. log4j, reload4j, JUL, logback, etc).

Limits

We recommend a 1000 QPS limit for sending us requests. You may send up to 2000 events per batch request, and can thus send up to 2M events/sec. Sending more than 2000 events per batch will result in a 400 error.

Code Example

Please use the code example below as a template on sending your conversion events to Snap Conversion API. More conversion parameters are expected to be provided in practice.

import com.snap.business.sdk.v3.api.ConversionApiClient;
import com.snap.business.sdk.v3.model.CapiEvent;
import com.snap.business.sdk.v3.util.ServerEnv;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

public class Example {
public static void main(String[] args) {
ConversionApiClient capiClient =
new ConversionApiClient.Builder()
.setAccessToken("<capi_access_token>") // Required
.setServerEnv(SERVER_ENV.PROD) // Or SERVER_ENV.Staging Required
.setOkHttpClient(okHttpClient) // Optional
.withDebuggingEnabled() // Optional
.withInternalDebuggingEnabled() // Optional
.build();

CapiEvent capiEvent = new CapiEvent();
capiEvent.setEventName("purchase");
capiEvent.setEventTime(1712009009L);
capiEvent.setActionSource("web");
capiEvent.dataProcessingOptions(Collections.singletonList("LDU"));

UserData userData = new UserData();
userData.setEm(
Collections.singletonList(
"7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"));
capiEvent.setUserData(userData);

CustomData customData = new CustomData();
customData.setCurrency("USD");
customData.setValue(BigDecimal.valueOf(142.52));
capiEvent.setCustomData(customData);

// Send Event Sync
EventResponse apiResponse = capiClient.sendEvent(testAssetId, capiPixelEvent);
// Send Batch Events Sync
EventResponse apiResponseBatch = capiClient.sendEventsBatch(testAssetId, capiBatchEvents);

// Send Event Async
capiClient.sendEventAsync(testAssetId, capiPixelEvent);

// Send Batch Events Async
capiClient.sendEventsBatchAsync(testAssetId, capiBatchEvents);
}
}
Was this page helpful?
Yes
No

AI-Powered Search