· Flutter 개발 · 7 min read

Flutter Android 17 SMS OTP 오류 - READ_SMS 대신 SMS Retriever로 바꾸는 조건

Flutter 앱이 Android 17에서 SMS OTP를 읽지 못하거나 3시간 늦게 받는다면 READ_SMS 재시도보다 SMS Retriever와 User Consent로 인증 흐름을 바꿔야 하는 조건을 정리한다.

Flutter Android 17 SMS OTP 인증 흐름과 휴대폰 메시지

이 그림에서 봐야 할 부분은 앱이 SMS 받은편지함을 훑는 구조가 아니라, 인증 앱으로 전달되는 OTP 경로를 사용해야 한다는 점이다.

Android 17(API 37)을 타깃으로 올린 Flutter 앱에서 READ_SMS나 SMS_RECEIVED_ACTION으로 인증번호를 읽고 있다면 그대로 출시하면 안 된다. 일반 SMS 형식의 OTP는 대부분 앱에서 최대 3시간 접근이 지연될 수 있다. 휴대폰 번호 로그인처럼 사용자가 즉시 인증해야 하는 앱은 SMS Retriever를 우선 적용하고, SMS 문구를 통제할 수 없는 외부 발송 서비스라면 SMS User Consent를 대안으로 둬야 한다. 단순히 OTP 입력창만 제공하고 사용자가 직접 입력하는 앱에는 이 마이그레이션이 필수는 아니다.

Android 17에서 달라지는 범위

Android 공식 문서 기준으로 WebOTP 메시지 보호는 target API와 관계없이 적용되고, 표준 SMS OTP 보호는 target API 37 이상 앱에 추가 적용된다. 지연 중에는 SMS_RECEIVED_ACTION이 전달되지 않고 SMS Provider 조회도 필터링된다.

현재 방식Android 17 조건출시 판단
READ_SMS로 받은편지함 조회표준 OTP가 지연될 수 있음자동 인증 용도로 폐기
SMS Retriever앱 해시가 포함된 SMS만 앱에 전달서버 문구를 통제할 수 있으면 우선 선택
SMS User Consent사용자가 한 번 읽기를 승인외부 SMS 사업자·문구 변경 시 대안
수동 입력OS가 SMS를 앱에 전달할 필요 없음가장 단순하지만 UX는 낮아짐

핵심은 Flutter 위젯을 고치는 일이 아니라 Android 네이티브 인증 경로를 바꾸는 일이다. sms_autofill처럼 받은편지함 권한이나 브로드캐스트에 의존하는 설정이 있다면 플러그인의 Android 구현을 확인해야 한다. 이름에 “autofill”이 들어갔다는 이유만으로 SMS Retriever를 쓴다고 가정하면 안 된다.

Flutter 프로젝트에서 바꿀 순서

권한과 서버 메시지를 분리해서 확인하면, Android 17 에뮬레이터에서 무작정 재전송을 반복하는 시간을 줄일 수 있다.

rg -n "READ_SMS|RECEIVE_SMS|SMS_RECEIVED|sms_autofill|SmsRetriever" \
  lib android pubspec.yaml

AndroidManifest.xml의 READ_SMS, RECEIVE_SMS와 SMS 수신 리시버를 직접 사용하고 있다면 제거 가능성을 검토한다. Flutter 쪽은 Google Play services의 SmsRetriever 또는 SmsUserConsent를 감싼 플러그인으로 교체하고, 성공·실패·5분 타임아웃을 Dart 상태로 전달하게 만든다. Google API 문서상 두 API의 대기 시간은 5분이므로, 그 뒤에는 수동 입력으로 전환해야 한다.

서버가 SMS 내용을 만들 수 있다면 앱 서명 해시를 포함한 Retriever 형식으로 바꾼다. 해시는 Debug 키, 자체 Release 키, Google Play 앱 서명 키가 서로 다를 수 있다. 따라서 개발 빌드에서 성공한 해시를 운영 서버에 복사하면 “Debug에서는 되는데 Play 배포판에서는 안 되는” 인증 오류가 생긴다.

<#> 인증번호는 123456입니다.
앱 이름에서 5분 안에 입력하세요.
FA+9q1AbCdE

위 문구의 해시는 예시일 뿐이다. 실제 앱 해시로 바꾸고, 서버가 여러 앱 변형에 SMS를 보낸다면 flavor·applicationId·서명 키별 값을 분리한다. 외부 SMS 사업자가 문구를 바꾸거나 해시를 제거한다면 User Consent 경로를 검토하고, 사용자가 승인할 수 없는 상황에는 수동 입력을 남긴다.

출시 전 확인표

  • targetSdk가 37 이상인 빌드에서 OTP 수신을 확인했다.
  • READ_SMS·RECEIVE_SMS 의존성과 리시버를 검색했다.
  • Debug와 Play App Signing의 앱 해시를 서버 문구에 구분했다.
  • Retriever 5분 만료 뒤 수동 입력으로 전환된다.
  • SMS를 읽지 못해도 재전송 횟수와 잠금 정책이 무한 반복되지 않는다.
  • WebOTP를 사용한다면 도메인 검증과 의도한 앱 연결을 따로 확인했다.

Android 17 대응 때문에 SMS 권한을 계속 추가하거나 3시간을 기다리는 재시도 로직을 넣는 것은 해결책이 아니다. 받은편지함을 읽는 구현은 표준 OTP 보호와 충돌할 수 있으므로, 앱이 SMS 발송 형식을 통제하면 Retriever, 통제하지 못하면 User Consent, 둘 다 불가능하면 수동 입력으로 인증 경로를 명시적으로 나누는 편이 안전하다.

참고 문서: Android 17 동작 변경 - SMS OTP 보호, Android 17 대상 앱 동작 변경, Google SMS Retriever API, Android 인증 보안 안내.

Share:
Back to Blog