SDK 인증 설정

SDK 인증을 통해 로그인한 사용자를 대신하여 SDK 요청에 암호화 증명(서버 측에서 생성됨)을 제공할 수 있습니다.

작동 방식

앱에서 이 기능을 활성화한 후에는 유효하지 않거나 누락된 JSON 웹 토큰(JWT)이 포함된 모든 요청을 거부하도록 Braze 대시보드를 구성할 수 있습니다. 여기에는 다음이 포함됩니다:

• 커스텀 이벤트, 속성, 구매 및 세션 데이터 전송
• Braze 워크스페이스에서 새 사용자 만들기
• 표준 고객 프로필 속성 업데이트
• 메시지 수신 또는 트리거

이제 인증되지 않은 로그인 사용자가 앱의 SDK API 키를 사용하여 다른 사용자를 사칭하는 등의 악의적인 행동을 수행하는 것을 방지할 수 있습니다.

인증 설정

1단계: 서버 설정

1.1단계: 공개/비공개 키 쌍 생성

RSA256 공개/비공개 키 쌍을 생성합니다. 공개 키는 최종적으로 Braze 대시보드에 추가되며, 비공개 키는 서버에 안전하게 저장해야 합니다.

RS256 JWT 알고리즘과 함께 사용할 2048비트의 RSA 키를 권장합니다.

1.2단계: 현재 사용자를 위한 JSON 웹 토큰 생성

비공개 키를 확보한 후, 서버 측 애플리케이션은 현재 로그인한 사용자에게 앱 또는 웹사이트로 JWT를 반환해야 합니다.

일반적으로 이 로직은 앱이 현재 고객 프로필을 요청하는 곳 어디에서나 사용할 수 있습니다. 예를 들어 로그인 엔드포인트나 앱이 현재 고객 프로필을 새로고침하는 곳이 될 수 있습니다.

JWT를 생성할 때 다음 필드가 필요합니다:

JWT 헤더

JWT 페이로드

2단계: SDK 구성

이 기능은 다음 SDK 버전부터 사용할 수 있습니다:

2.1단계: Braze SDK에서 인증을 활성화합니다.

이 기능이 활성화되면 Braze SDK는 현재 사용자의 마지막으로 알려진 JWT를 Braze 서버에 대한 네트워크 요청에 추가합니다.

• web
• react native
• java
• kotlin
• objective-c
• swift
• dart
• flutter
• unity
• cordova
• .net maui (xamarin)
• expo

1
2
3
4
5
import * as braze from "@braze/web-sdk";
braze.initialize("YOUR-API-KEY-HERE", {
  baseUrl: "YOUR-SDK-ENDPOINT-HERE",
  enableSdkAuthentication: true,
});

1
2
3
4
5
6
7
8
9
10
11
12
import BrazeKit
import braze_react_native_sdk

let configuration = Braze.Configuration(
  apiKey: "{YOUR-BRAZE-API-KEY}",
  endpoint: "{YOUR-BRAZE-ENDPOINT}"
)
configuration.api.sdkAuthentication = true
let braze = BrazeReactBridge.perform(
  #selector(BrazeReactBridge.initBraze(_:)),
  with: configuration
).takeUnretainedValue() as! Braze

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
3
BrazeConfig.Builder brazeConfigBuilder = new BrazeConfig.Builder()
    .setIsSdkAuthenticationEnabled(true);
Braze.configure(this, brazeConfigBuilder.build());

1
2
3
BrazeConfig.Builder brazeConfigBuilder = BrazeConfig.Builder()
    .setIsSdkAuthenticationEnabled(true)
Braze.configure(this, brazeConfigBuilder.build())

1
2
3
4
5
6
BRZConfiguration *configuration =
    [[BRZConfiguration alloc] initWithApiKey:@"{BRAZE_API_KEY}"
                                    endpoint:@"{BRAZE_ENDPOINT}"];
configuration.api.sdkAuthentication = YES;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

1
2
3
4
5
let configuration = Braze.Configuration(apiKey: "{YOUR-BRAZE-API-KEY}",
                                        endpoint: "{YOUR-BRAZE-ENDPOINT}")
configuration.api.sdkAuthentication = true
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
let configuration = Braze.Configuration(apiKey: "{YOUR-BRAZE-API-KEY}", endpoint: "{YOUR-BRAZE-ENDPOINT}")
configuration.api.sdkAuthentication = true
let braze = Braze(configuration: configuration)

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
<key>SDKAuthenticationEnabled</key>
<true/>

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
<preference name="com.braze.ios_enable_sdk_authentication" value="true" />

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
3
var configuration = new BRZConfiguration("YOUR-API-KEY", "YOUR-ENDPOINT");
configuration.Api.SdkAuthentication = true;
var braze = new Braze(configuration);

1
<bool name="com_braze_sdk_authentication_enabled">true</bool>

1
2
3
4
5
6
7
8
9
10
11
12
{
  "expo": {
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          "enableSdkAuthentication": true
        }
      ]
    ]
  }
}

2.2단계: 현재 사용자의 JWT 설정

앱에서 Braze changeUser 메서드를 호출할 때마다 서버 측에서 생성된 JWT도 함께 제공하세요.

현재 사용자의 세션 중간에 토큰을 새로고침하도록 구성할 수도 있습니다.

• web
• react native
• java
• kotlin
• objective-c
• swift
• dart
• flutter
• unity
• cordova
• .net maui (xamarin)
• expo

1
2
import * as braze from "@braze/web-sdk";
braze.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
2
import * as braze from "@braze/web-sdk";
braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
Braze.getInstance(this).changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
Braze.getInstance(this).setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
Braze.getInstance(this).changeUser("NEW-USER-ID", "JWT-FROM-SERVER")

1
Braze.getInstance(this).setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER")

1
[AppDelegate.braze changeUser:@"userId" sdkAuthSignature:@"JWT-FROM-SERVER"];

1
[AppDelegate.braze setSDKAuthenticationSignature:@"NEW-JWT-FROM-SERVER"];

1
AppDelegate.braze?.changeUser(userId: "userId", sdkAuthSignature: "JWT-FROM-SERVER")

1
AppDelegate.braze?.set(sdkAuthenticationSignature: "NEW-JWT-FROM-SERVER")

1
braze.changeUser("userId", sdkAuthSignature: "JWT-FROM-SERVER")

1
braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER")

1
2
3
4
import 'package:braze_plugin/braze_plugin.dart';

BrazePlugin braze = BrazePlugin();
braze.changeUser("NEW-USER-ID", sdkAuthSignature: "JWT-FROM-SERVER");

1
2
3
4
import 'package:braze_plugin/braze_plugin.dart';

BrazePlugin braze = BrazePlugin();
braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
BrazeBinding.ChangeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
BrazeBinding.SetSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
BrazePlugin.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
BrazePlugin.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
Braze.SharedInstance?.ChangeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
Braze.SharedInstance?.SetSDKAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
Braze.GetInstance(this).ChangeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
Braze.GetInstance(this).SetSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.changeUser("NEW-USER-ID", "JWT-FROM-SERVER");

1
2
3
import Braze from '@braze/react-native-sdk';

Braze.setSdkAuthenticationSignature("NEW-JWT-FROM-SERVER");

2.3단계: 잘못된 토큰에 대한 콜백 함수 등록

이 기능이 필수로 설정된 경우 다음 시나리오에서는 SDK 요청이 Braze에 의해 거부됩니다:

• JWT가 Braze API에 도착했을 때 이미 만료된 경우
• JWT가 비어 있거나 누락된 경우
• JWT가 Braze 대시보드에 업로드한 공개 키에 대해 검증에 실패한 경우

subscribeToSdkAuthenticationFailures를 사용하여 SDK 요청이 이러한 이유 중 하나로 실패할 때 알림을 받도록 구독할 수 있습니다. 콜백 함수는 관련 errorCode, 오류 reason, 요청의 userId(사용자는 익명일 수 없음), 그리고 오류를 유발한 인증 토큰(JWT)을 포함하는 오브젝트를 전달합니다.

실패한 요청은 앱이 새로운 유효한 JWT를 제공할 때까지 주기적으로 재시도됩니다. 해당 사용자가 여전히 로그인되어 있는 경우, 이 콜백을 사용하여 서버에서 새 JWT를 요청하고 Braze SDK에 이 새 유효 토큰을 제공할 수 있습니다.

인증 오류가 발생하면 오류의 userId가 현재 로그인한 사용자와 일치하는지 확인한 후, 서버에서 새 서명을 가져와 Braze SDK에 제공하십시오. 이러한 오류를 모니터링 또는 오류 보고 서비스에 기록할 수도 있습니다.

• web
• react native
• java
• kotlin
• objective-c
• swift
• dart
• flutter
• unity
• cordova
• .net maui (xamarin)
• expo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import * as braze from "@braze/web-sdk";

braze.subscribeToSdkAuthenticationFailures((error) => {
  console.error("SDK authentication failed:", error);
  console.log("Error code:", error.errorCode);
  console.log("User ID:", error.userId);
  // Note: Do not log error.signature as it contains sensitive authentication credentials
  
  // Verify the error.userId matches the currently logged-in user
  // Fetch a new token from your server and set it
  fetchNewSignature(error.userId).then((newSignature) => {
    braze.setSdkAuthenticationSignature(newSignature);
  });
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import Braze from '@braze/react-native-sdk';

const sdkAuthErrorSubscription = Braze.addListener(
  Braze.Events.SDK_AUTHENTICATION_ERROR,
  (error) => {
    console.log(`SDK Authentication for ${error.userId} failed with error code ${error.errorCode}.`);
    
    const updated_jwt = getNewTokenSomehow(error);
    Braze.setSdkAuthenticationSignature(updated_jwt);
  }
);

// Don't forget to remove the listener when done
// sdkAuthErrorSubscription.remove();

1
2
3
4
Braze.getInstance(this).subscribeToSdkAuthenticationFailures(error -> {
    String newToken = getNewTokenSomehow(error);
    Braze.getInstance(getContext()).setSdkAuthenticationSignature(newToken);
});

1
2
3
4
Braze.getInstance(this).subscribeToSdkAuthenticationFailures({ error: BrazeSdkAuthenticationErrorEvent ->
    val newToken: String = getNewTokenSomehow(error)
    Braze.getInstance(getContext()).setSdkAuthenticationSignature(newToken)
})

1
2
3
4
5
6
7
8
9
10
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
braze.sdkAuthDelegate = delegate;
AppDelegate.braze = braze;

// Method to implement in delegate
- (void)braze:(Braze *)braze sdkAuthenticationFailedWithError:(BRZSDKAuthenticationError *)error {
  NSLog(@"Invalid SDK Authentication Token.");
  NSString *newSignature = getNewTokenSomehow(error);
  [AppDelegate.braze setSDKAuthenticationSignature:newSignature];
}

1
2
3
4
5
6
7
8
9
10
let braze = Braze(configuration: configuration)
braze.sdkAuthDelegate = delegate
AppDelegate.braze = braze

// Method to implement in delegate
func braze(_ braze: Braze, sdkAuthenticationFailedWithError error: Braze.SDKAuthenticationError) {
  print("Invalid SDK Authentication Token.")
  let newSignature = getNewTokenSomehow(error)
  AppDelegate.braze?.set(sdkAuthenticationSignature: newSignature)
}

1
2
3
4
5
braze.setBrazeSdkAuthenticationErrorCallback((BrazeSdkAuthenticationError error) async {
  print("Invalid SDK Authentication Token.");
  final newSignature = getNewTokenSomehow(error);
  braze.setSdkAuthenticationSignature(newSignature);
});

1
2
3
4
5
6
7
8
9
10
import 'package:braze_plugin/braze_plugin.dart';

BrazePlugin braze = BrazePlugin();

braze.setBrazeSdkAuthenticationErrorCallback((BrazeSdkAuthenticationError error) async {
  print("SDK Authentication for ${error.userId} failed with error code ${error.errorCode}.");
  
  String newSignature = getNewTokenSomehow(error);
  braze.setSdkAuthenticationSignature(newSignature);
});

1
2
3
4
5
6
7
8
9
public class SdkAuthDelegate : BRZSdkAuthDelegate
{
  public void Braze(Braze braze, BRZSDKAuthenticationError error)
  {
    Debug.Log("Invalid SDK Authentication Token.");
    string newSignature = GetNewTokenSomehow(error);
    BrazeBinding.SetSdkAuthenticationSignature(newSignature);
  }
}

1
2
3
4
Braze.GetInstance(this).SubscribeToSdkAuthenticationFailures((error) => {
  string newToken = GetNewTokenSomehow(error);
  Braze.GetInstance(this).SetSdkAuthenticationSignature(newToken);
});

1
2
3
4
5
6
BrazePlugin.subscribeToSdkAuthenticationFailures((error) => {
  console.log(`SDK Authentication for ${error.user_id} failed with error code ${error.error_code}.`);
  
  const newSignature = getNewTokenSomehow(error);
  BrazePlugin.setSdkAuthenticationSignature(newSignature);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class SdkAuthDelegate : BRZSdkAuthDelegate
{
  public override void Braze(Braze braze, BRZSDKAuthenticationError error)
  {
    Console.WriteLine("Invalid SDK Authentication Token.");
    string newSignature = GetNewTokenSomehow(error);
    Braze.SharedInstance?.SetSDKAuthenticationSignature(newSignature);
  }
}

// Set the delegate during initialization
var configuration = new BRZConfiguration("YOUR-API-KEY", "YOUR-ENDPOINT");
configuration.Api.SdkAuthentication = true;
var braze = new Braze(configuration);
braze.SdkAuthDelegate = new SdkAuthDelegate();

1
2
3
4
Braze.GetInstance(this).SubscribeToSdkAuthenticationFailures((error) => {
  string newToken = GetNewTokenSomehow(error);
  Braze.GetInstance(this).SetSdkAuthenticationSignature(newToken);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import Braze from '@braze/react-native-sdk';

const sdkAuthErrorSubscription = Braze.addListener(
  Braze.Events.SDK_AUTHENTICATION_ERROR,
  (error) => {
    console.log(`SDK Authentication for ${error.userId} failed with error code ${error.errorCode}.`);
    
    const updated_jwt = getNewTokenSomehow(error);
    Braze.setSdkAuthenticationSignature(updated_jwt);
  }
);

// Don't forget to remove the listener when done
// sdkAuthErrorSubscription.remove();

3단계: 대시보드에서 인증 활성화

다음으로, 이전에 설정한 앱에 대해 Braze 대시보드에서 인증을 활성화할 수 있습니다.

Braze 대시보드에서 앱의 SDK 인증 설정이 필수로 설정되지 않는 한, SDK 요청은 인증 없이 평소처럼 계속 진행됩니다.

통합에 문제가 발생한 경우(예: 앱이 SDK에 토큰을 잘못 전달하거나 서버가 잘못된 토큰을 생성하는 경우), Braze 대시보드에서 이 기능을 비활성화하면 데이터가 검증 없이 평소처럼 다시 흐르기 시작합니다.

적용 옵션

대시보드 설정 관리 페이지에서 각 앱에는 Braze가 요청을 검증하는 방식을 제어하는 세 가지 SDK 인증 상태가 있습니다.

선택 사항 설정은 이 기능이 앱의 SDK 트래픽에 미칠 잠재적 영향을 모니터링하는 유용한 방법입니다.

잘못된 JWT는 선택 사항 및 필수 상태 모두에서 보고되지만, 필수 상태에서만 SDK 요청이 거부되어 앱이 재시도하고 새 JWT를 요청하게 됩니다.

공개 키 관리

공개 키 추가

앱당 최대 세 개의 공개 키(기본, 보조 및 3차)를 추가할 수 있습니다. 필요한 경우 동일한 키를 둘 이상의 앱에 추가할 수도 있습니다. 공개 키를 추가하려면:

1. Braze 대시보드로 이동하여 설정 > 앱 설정을 선택합니다.
2. 사용 가능한 앱 목록에서 앱을 선택합니다.
3. SDK 인증에서 공개 키 추가를 선택합니다.
4. 선택적 설명을 입력하고, 공개 키를 붙여넣은 다음, 공개 키 추가를 선택합니다.

새 기본 키 할당

보조 키 또는 3차 키를 새 기본 키로 할당하려면:

1. Braze 대시보드로 이동하여 설정 > 앱 설정을 선택합니다.
2. 사용 가능한 앱 목록에서 앱을 선택합니다.
3. SDK 인증에서 키를 선택하고 관리 > 기본 키로 설정을 선택합니다.

키 삭제

기본 키를 삭제하려면 먼저 새 기본 키를 할당한 다음, 키를 삭제합니다. 기본 키가 아닌 키를 삭제하려면:

1. Braze 대시보드로 이동하여 설정 > 앱 설정을 선택합니다.
2. 사용 가능한 앱 목록에서 앱을 선택합니다.
3. SDK 인증에서 기본 키가 아닌 키를 선택하고 관리 > 공개 키 삭제를 선택합니다.

분석

각 앱은 이 기능이 선택 사항 및 필수 상태에 있는 동안 수집된 SDK 인증 오류의 분석을 보여줍니다.

데이터는 실시간으로 제공되며, 차트의 포인트 위로 마우스를 가져가면 특정 날짜의 오류 내역을 볼 수 있습니다.

오류 코드

자주 묻는 질문(FAQ)

이 기능을 모든 앱에서 동시에 활성화해야 하나요?

아니요. 이 기능은 특정 앱에 대해 활성화할 수 있으며 모든 앱에서 한 번에 사용할 필요는 없습니다.

내 앱의 이전 버전을 사용하는 사용자에게는 어떤 일이 발생하나요?

이 기능을 적용하기 시작하면, 이전 앱 버전에서 보낸 요청은 Braze에 의해 거부되고 SDK에 의해 재시도됩니다. 사용자가 앱을 지원되는 버전으로 업그레이드하면 대기줄에 추가된 요청이 다시 수락되기 시작합니다.

가능하다면 다른 필수 업그레이드와 마찬가지로 사용자가 업그레이드하도록 푸시해야 합니다. 또는 허용 가능한 비율의 사용자가 업그레이드할 때까지 기능을 선택 사항으로 유지할 수 있습니다.

JWT를 생성할 때 어떤 만료 기간을 사용해야 하나요?

평균 세션 지속 시간, 세션 쿠키/토큰 만료 또는 애플리케이션이 현재 고객 프로필을 새로고침하는 빈도 중 더 높은 값을 사용하는 것이 좋습니다.

JWT가 사용자의 세션 중간에 만료되면 어떻게 되나요?

사용자의 토큰이 세션 도중에 만료되는 경우, SDK에는 콜백 함수가 있어 앱에 Braze로 데이터를 계속 전송하려면 새 JWT가 필요하다는 것을 알려줍니다.

서버 측 통합이 중단되어 더 이상 JWT를 생성할 수 없으면 어떻게 되나요?

서버에서 JWT를 제공할 수 없거나 통합 문제가 발견되는 경우 언제든지 Braze 대시보드에서 해당 기능을 비활성화할 수 있습니다.

비활성화되면 보류 중인 실패한 모든 SDK 요청이 결국 SDK에 의해 재시도되고 Braze에 의해 수락됩니다.

왜 이 기능은 공유 비밀 대신 공개/비공개 키를 사용하나요?

공유 비밀을 사용할 때 Braze 대시보드 페이지와 같은 해당 공유 비밀에 접근할 수 있는 사람은 누구나 토큰을 생성하고 최종 사용자를 사칭할 수 있습니다.

대신 공개/비공개 키를 사용하므로, Braze 직원은 물론이고 귀사의 사용자도 비공개 키에 접근할 수 없습니다.

거부된 요청은 어떻게 재시도되나요?

인증 오류로 인해 요청이 거부되면 SDK는 사용자의 JWT를 새로고침하는 데 사용되는 콜백을 호출합니다.

요청은 지수 백오프 접근 방식을 사용하여 주기적으로 재시도됩니다. 50번 연속으로 시도에 실패하면 다음 세션이 시작될 때까지 재시도가 일시 중지됩니다. 각 SDK에는 데이터 플러시를 수동으로 요청하는 메서드도 있습니다.

익명 사용자에게 SDK 인증을 사용할 수 있나요?

아니요. SDK 인증은 웹사이트가 누군가의 신원을 확인하는 방식으로 작동하므로, 식별된 사용자에게만 적용됩니다. 익명 사용자의 경우 확인할 신원이 없습니다.

적용은 changeUser가 호출된 후에 시작됩니다. 사용자가 식별되기 전(예: 가입 전에 익명으로 탐색하는 동안)에는 SDK가 JWT 없이도 Braze에 데이터를 전송할 수 있습니다. changeUser가 호출된 후에는 해당 식별된 프로필에 대한 요청에 유효한 JWT가 필요합니다.

이는 일반적인 사용자 여정이 다음과 같을 수 있음을 의미합니다:

1. 사용자가 익명으로 사이트를 방문하거나 앱을 엽니다. Braze는 JWT 없이 이 활동을 수집합니다.
2. 사용자가 가입하거나 로그인하면, 앱이 external_id와 함께 changeUser를 호출합니다.
3. Braze는 해당 사용자의 활동을 계속 수집하며, 해당 식별된 프로필에 대한 요청에 SDK 인증이 적용됩니다.

SDK 인증은 사용자 별칭과 함께 작동하나요?

아니요. SDK 인증에는 external_id가 필요합니다. braze_id 또는 alias_id만 사용 가능한 경우에는 설정할 수 없으므로, 별칭 전용 프로필은 SDK 인증을 사용할 수 없습니다.

SDK 인증을 활성화하면 인증되지 않은 활동 수집이 차단되나요?

아니요. SDK 인증은 정당한 익명 활동 수집을 차단하지 않습니다. changeUser로 프로필이 식별된 후에만 적용됩니다.