XGameUiShowWebAuthenticationWithOptionsAsync

[アーティクル]
05/09/2023

ユーザーが実行中のタイトルに資格情報を直接提供せずに外部の Web サイトやサービスへのアクセスを委任できるようにする Web UI を (場合によっては全画面で) 表示する、非同期認証要求を開始します。

構文

STDAPI XGameUiShowWebAuthenticationWithOptionsAsync(
    _In_ XAsyncBlock* async,
    _In_ XUserHandle requestingUser,
    _In_z_ const char* requestUri,
    _In_z_ const char* completionUri,
    _In_ XGameUiWebAuthenticationOptions options
    ) noexcept;
)

パラメーター

async _In_
型: XAsyncBlock*

XAsyncRun に渡された XAsyncBlock へのポインター。

requestingUser _In_
型: XUserHandle

Web 認証を要求しているユーザーに対するハンドル。

requestUri _In_z_
型: char*

ユーザーに表示される Web ビューの初期 URI (サービスに対するユーザー認証のためのフィールドを含んでいる可能性があります)。要求 URI は、セキュリティで保護された HTTPS アドレスである必要があります。

completionUri _In_z_
型: char*

Web 認証プロセスが正常に完了したことを表す URI を示します。 Web ビューが completionUri と一致する URI にナビゲートすると、Web ビューが閉じられ、呼び出し元のタイトルに制御が戻されます。

オプション &nbps;_In_ 型: XGameUiWebAuthenticationOptions

UI の全画面表示を試行するかどうかを指定するフラグ。 PC では、このフラグは無視されます。全画面表示は、PC でサポートされているオプションではありません。

戻り値

型: HRESULT

非同期呼び出しの HRESULT の成功またはエラーコードです。

結果を取得するには、AsyncBlock コールバック内または AsyncBlock 完了後に xgameuishowwebauthenticationresultsize と xgameuishowwebauthenticationresult を呼び出します。

解説

この非同期タスクが実行されると、システムによって Web ビューがユーザーに表示 (現在のアプリケーションに重ねて表示) されます。ユーザーはこのビューを操作するか、戻るボタンを押して閉じることができます。これによりユーザーは、外部の Web サイトやサービスへの認証アクセス許可を付与するために OAuth を使用できるようになります。これは、ゲームがゲーム内のハイライトをソーシャルメディアで共有することを認証するシナリオや、外部プロバイダーのユーザーデータを要求するシナリオなどで使用できます。

認証要求の結果は、XGameUiShowWebAuthenticationResult メソッドから返される XGameUiWebAuthenticationResultData オブジェクトに格納されます。

Web ビューが completionUri にナビゲートした結果として閉じられた場合、結果データ構造体の responseStatus フィールドは S_OK になります。

ユーザーが Web ビューをキャンセルするか、手動で閉じた場合、結果データ構造体の responseStatus フィールドは E_CANCELLED になります。

例

次のコード例は、Facebook を使用して OAuth を実行する方法を示しています。コードを簡潔にするために、この例にはメモリ割り当てのエラー処理は含まれていません。

// Use Facebook example for OAuth; client_id should correspond to your registered application.
const char completionUri[] = "https://www.facebook.com/connect/login_success.html"; 
const char requestUri[] =
    "https://www.facebook.com/dialog/oauth?"
    "client_id=000000000000000&"
    "redirect_uri=https%3A%2F%2Fwww.facebook.com%2Fconnect%2Flogin_success.html&"
    "response_type=token&"
    "sdk=xboxone";

// Allocate and initialize XAsyncBlock for asynchronous authentication operation.
XAsyncBlock* block = new XAsyncBlock();
ZeroMemory(block, sizeof(XAsyncBlock));
block->callback = [](XAsyncBlock* block)
{
    // Query required size and allocate buffer for authentication result data.
    uint32_t bufferSize = 0;
    FAIL_FAST_IF_FAILED(XGameUiShowWebAuthenticationResultSize(block, &bufferSize));
    uint8_t* buffer = new uint8_t[bufferSize];

    // The currentUser is initialized with user to authenticate for.
    XGameUiWebAuthenticationResultData* resultData = nullptr;
    FAIL_FAST_IF_FAILED(XGameUiShowWebAuthenticationResult(
        block,
        bufferSize,
        buffer,
        &resultData,
        nullptr
        ));

    //
    // Use the result data here. If resultData->responseStatus is S_OK, then web authentication was successful.
    //

    // Free allocated buffer and XAsyncBlock.
    delete[] buffer;
    delete block;
};

//  Begin asynchronous authentication operation.
XUserHandle currentUser = GetCurrentUserForAuthentication();
FAIL_FAST_IF_FAILED(XGameUiShowWebAuthenticationWithOptionsAsync(
    block,
    currentUser,
    requestUri,
    completionUri,
    XGameUiWebAuthenticationOptions::PreferFullscreen
    ));

要件

ヘッダー: XGameUI.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

次の方法で共有

XGameUiShowWebAuthenticationWithOptionsAsync

構文

パラメーター

戻り値

解説

例

要件

関連項目

その他のリソース