소프트웨어 개발 키트 인증 설정하기

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

How it works

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

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

이제 인증되지 않은 로그인 사용자가 앱의 소프트웨어 개발 키트 API 키를 사용하여 다른 사용자를 가장하는 등의 악의적인 작업을 수행하는 것을 방지할 수 있습니다.

인증 설정

1단계: 서버 설정

1.1단계: 공개/비공개 키 쌍 {#generate-keys} 생성

RSA256 공개/비공개 키 쌍을 생성합니다. 비공개 키는 귀하의 서버에 안전하게 저장되어야 하며, 공개 키는 결국 Braze 대시보드에 추가됩니다.

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

1.2단계: 현재 사용자 {#create-jwt}을(를) 위한 JSON 웹 토큰을 생성하십시오

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

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

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

JWT 헤더

JWT 페이로드

2단계: 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-callback}에 대한 콜백 함수를 등록하십시오

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

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

subscribeToSdkAuthenticationFailures를 사용하여 SDK 요청이 이러한 이유 중 하나로 실패할 때 알림을 받기 위해 가입할 수 있습니다. 콜백 함수에는 오류에 대한 관련 errorCode, 오류에 대한 reason, 요청의 userId (사용자는 익명일 수 없음), 오류를 일으킨 인증 토큰(JWT)을 반환합니다.

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

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

• 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 대시보드에서 인증을 활성화할 수 있습니다.

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

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

적용 옵션

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

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

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

공개 키 관리

공개 키 추가

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

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

새 기본 키 할당

보조 키 또는 3차 키를 새 기본 키로 할당하려면 다음을 수행합니다.

1. Braze 대시보드로 이동하여 설정 > 앱 설정을 선택합니다.
2. 사용 가능한 앱 목록에서 앱을 선택하세요.
3. 소프트웨어 개발 키트 인증에서 키를 선택하고 관리 > 기본 키 만들기를 선택합니다.

키 삭제

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

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

분석

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

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

오류 코드

자주 묻는 질문(FAQ)

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

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

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

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

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

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

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

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

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

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

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

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

왜 이 기능은 공유 비밀 대신 공개/개인 키를 사용합니까?

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

대신에, 우리는 공개/비공개 키를 사용하여 Braze 직원들조차 (대시보드 사용자들은 말할 것도 없이) 귀하의 비공개 키에 접근할 수 없도록 합니다.

거부된 요청은 어떻게 재시도됩니까?

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

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

익명 사용자에게 소프트웨어 개발 키트 인증을 사용할 수 있나요?

아니요. 익명 사용자의 경우 소프트웨어 개발 키트 인증이 필요하지 않습니다.